ConnectionSecret

ConnectionSecret manifests encapsulate credentials and tokens used by the query engine to access external systems. They keep sensitive data out of datasource definitions and SQL queries.

Spec overview

apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: exampleSecret
spec:
  type: postgres | mysql | s3 | gcs | http | r2 | azure | huggingface | webdav
  scope: "" # optional path prefix
  provider: config # or credential_chain
  # one type-specific block: postgres, mysql, s3, gcs, http, r2, azure, huggingface, webdav

Type-specific blocks:

• postgres – see postgresAuthSpec (password or passwordFromEnv).
• mysql – see mysqlAuthSpec.
• s3 – see s3AuthSpec (access keys, region, endpoint).
• gcs – see gcsAuthSpec.
• http – see httpAuthSpec (basic auth or bearer token).
• r2 – see r2AuthSpec.
• azure – see azureAuthSpec.
• huggingface – see huggingfaceAuthSpec.
• webdav – see webdavAuthSpec (username and password for WebDAV servers).

scope can be used to limit where a secret applies, for example s3://my-bucket.

PostgreSQL credentials via environment variable

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: postgresCredentials
spec:
  type: postgres
  postgres:
    passwordFromEnv: POSTGRES_PASSWORD

Use the secret from a datasource:

apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: orders_pg
spec:
  type: postgres_query
  connection:
    host: ${DB_HOST:db.example.com}
    port: 5432
    database: analytics
    schema: public
    user: reporting
    secret: postgresCredentials
  query: |
    SELECT * FROM fact_orders;

S3 access key

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: s3Access
spec:
  type: s3
  scope: s3://my-report-bucket
  s3:
    keyIdFromEnv: AWS_ACCESS_KEY_ID
    secretFromEnv: AWS_SECRET_ACCESS_KEY
    region: eu-central-1

HTTP bearer token

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: httpApi
spec:
  type: http
  http:
    bearerTokenFromEnv: API_TOKEN

HTTP proxy configuration

The CLI handles HTTP proxies in two distinct contexts:

1. DuckDB extension downloads: The CLI automatically respects the http_proxy environment variable (along with http_proxy_username and http_proxy_password) when downloading DuckDB extensions. This happens transparently during startup.

2. Datasource HTTP access: For HTTP/HTTPS datasource access (e.g., reading remote CSV/Parquet files), you must explicitly configure a proxy via a ConnectionSecret of type http. The http_proxy environment variable is not automatically applied to datasource requests.

Proxy via environment variable

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: httpProxy
spec:
  type: http
  http:
    httpProxyFromEnv: http_proxy
    httpProxyUsernameFromEnv: http_proxy_username
    httpProxyPasswordFromEnv: http_proxy_password

Proxy with inline values

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: httpProxyInline
spec:
  type: http
  http:
    httpProxy: "http://proxy.example.com:8080"
    httpProxyUsername: "proxyuser"
    httpProxyPasswordFromEnv: PROXY_PASSWORD

Scoped proxy

Use scope to apply the proxy only to specific URL prefixes:

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: internalProxy
spec:
  type: http
  scope: "https://internal.example.com"
  http:
    httpProxy: "http://internal-proxy:3128"

Hugging Face token

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: huggingface
spec:
  type: huggingface
  huggingface:
    tokenFromEnv: HUGGINGFACE_TOKEN

WebDAV credentials

WebDAV secrets allow you to access files on WebDAV servers, including Hetzner Storage Boxes. This uses the webdavfs DuckDB community extension.

Generic WebDAV server

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: webdavStorage
spec:
  type: webdav
  scope: webdav://webdav-server.example.com/
  webdav:
    username: myuser
    passwordFromEnv: WEBDAV_PASSWORD

Hetzner Storage Box

Hetzner Storage Boxes use the special storagebox:// URL scheme:

---
apiVersion: bino.bi/v1alpha1
kind: ConnectionSecret
metadata:
  name: hetznerStorageBox
spec:
  type: webdav
  scope: storagebox://u123456
  webdav:
    username: u123456
    passwordFromEnv: HETZNER_STORAGEBOX_PASSWORD

Using WebDAV files in a DataSource

Once the secret is configured, you can reference files on the WebDAV server:

---
apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: salesData
spec:
  type: parquet
  path: webdav://webdav-server.example.com/reports/sales.parquet

Or for Hetzner Storage Box:

---
apiVersion: bino.bi/v1alpha1
kind: DataSource
metadata:
  name: salesData
spec:
  type: parquet
  path: storagebox://u123456/reports/sales.parquet

Always prefer *FromEnv fields over inline secrets in manifests.