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.

Minimal definition

The smallest well-formed ConnectionSecret: pick a secret type and fill the credential block of the same name. This one holds a PostgreSQL password that is read from an environment variable at build time.

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

The other secret types work the same way - set type to mysql, s3, gcs, http, r2, azure or huggingface and add the block with that name, as in S3 access key, HTTP bearer token and Hugging Face token. All attributes are listed in the Attribute Reference below.

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.

Attribute Reference

Common Metadata

Attribute	Type	Required	Default	Description
apiVersion	string	yes	-	Must be bino.bi/v1alpha1.
kind	string	yes	-	Must be ConnectionSecret.
metadata.name	string	yes	-	Unique identifier. Referenced by the secret field of a datasource.
metadata.labels	object	no	-	Key-value pairs for categorization and constraint matching.
metadata.annotations	object	no	-	Arbitrary key-value metadata, not used by the system.
metadata.description	string	no	-	Free-form description.
metadata.constraints	array	no	-	Conditional inclusion rules. See Constraints.

Spec Attributes

The credential block whose name matches spec.type is required; the other blocks do not apply and are ignored.

Attribute	Type	Required	Default	Description	Sample
spec.type	string	yes	-	The DuckDB secret type. Values: s3, gcs, http, r2, azure, postgres, mysql, huggingface.	type: postgres
spec.scope	string	no	-	Optional file path prefix that the secret applies to. Limits where the secret is used.	scope: s3://my-bucket
spec.provider	string	no	config	Secret provider. Use credential_chain for automatic discovery of ambient credentials.	provider: credential_chain
spec.postgres	object	with type: postgres	-	PostgreSQL credentials. Connection details (host, port, database, user) belong in the DataSource connection block.	postgres: { passwordFromEnv: POSTGRES_PASSWORD }
spec.postgres.password	string	one of password / passwordFromEnv	-	Database password for authentication.	password: "s3cret"
spec.postgres.passwordFromEnv	string	one of password / passwordFromEnv	-	Name of environment variable containing the database password (recommended over inline password).	passwordFromEnv: POSTGRES_PASSWORD
spec.mysql	object	with type: mysql	-	MySQL credentials. Connection details (host, port, database, user) belong in the DataSource connection block.	mysql: { passwordFromEnv: MYSQL_PASSWORD }
spec.mysql.password	string	one of password / passwordFromEnv	-	Database password for authentication.	password: "s3cret"
spec.mysql.passwordFromEnv	string	one of password / passwordFromEnv	-	Name of environment variable containing the database password (recommended over inline password).	passwordFromEnv: MYSQL_PASSWORD
spec.s3	object	with type: s3	-	AWS S3 authentication configuration (access keys, region, endpoint).	s3: { region: eu-central-1 }
spec.s3.keyId	string	no	-	AWS access key ID.	keyId: AKIAIOSFODNN7EXAMPLE
spec.s3.keyIdFromEnv	string	no	-	Environment variable containing the AWS access key ID.	keyIdFromEnv: AWS_ACCESS_KEY_ID
spec.s3.secret	string	no	-	AWS secret access key.	secret: "wJalrXUtnFEMI..."
spec.s3.secretFromEnv	string	no	-	Environment variable containing the AWS secret access key.	secretFromEnv: AWS_SECRET_ACCESS_KEY
spec.s3.region	string	no	-	AWS region.	region: eu-central-1
spec.s3.sessionToken	string	no	-	AWS session token for temporary credentials.	sessionToken: "FwoGZXIvYXdz..."
spec.s3.sessionTokenFromEnv	string	no	-	Environment variable containing the AWS session token.	sessionTokenFromEnv: AWS_SESSION_TOKEN
spec.s3.endpoint	string	no	-	Custom S3 endpoint URL (for S3-compatible services).	endpoint: minio.example.com:9000
spec.s3.urlStyle	string	no	-	S3 URL style. Values: path, vhost.	urlStyle: path
spec.gcs	object	with type: gcs	-	Google Cloud Storage authentication configuration (HMAC access keys).	gcs: { keyIdFromEnv: GCS_KEY_ID }
spec.gcs.keyId	string	no	-	GCS access key ID.	keyId: GOOG1EEXAMPLE
spec.gcs.keyIdFromEnv	string	no	-	Environment variable containing the GCS access key ID.	keyIdFromEnv: GCS_KEY_ID
spec.gcs.secret	string	no	-	GCS secret access key.	secret: "abc123..."
spec.gcs.secretFromEnv	string	no	-	Environment variable containing the GCS secret access key.	secretFromEnv: GCS_SECRET
spec.http	object	with type: http	-	HTTP/HTTPS authentication and proxy configuration (basic auth, bearer token or proxy).	http: { bearerTokenFromEnv: API_TOKEN }
spec.http.username	string	no	-	HTTP basic auth username.	username: reporting
spec.http.usernameFromEnv	string	no	-	Environment variable containing the HTTP username.	usernameFromEnv: HTTP_USER
spec.http.password	string	no	-	HTTP basic auth password.	password: "s3cret"
spec.http.passwordFromEnv	string	no	-	Environment variable containing the HTTP password.	passwordFromEnv: HTTP_PASSWORD
spec.http.bearerToken	string	no	-	HTTP bearer token for authorization.	bearerToken: "eyJhbGci..."
spec.http.bearerTokenFromEnv	string	no	-	Environment variable containing the HTTP bearer token.	bearerTokenFromEnv: API_TOKEN
spec.http.httpProxy	string	no	-	HTTP proxy URL, used for datasource HTTP access. The CLI respects the http_proxy environment variable only for DuckDB extension downloads; datasource access requires this field or httpProxyFromEnv. See HTTP proxy configuration.	httpProxy: "http://proxy.example.com:8080"
spec.http.httpProxyFromEnv	string	no	-	Environment variable containing the HTTP proxy URL. Takes precedence if httpProxy is not set.	httpProxyFromEnv: http_proxy
spec.http.httpProxyUsername	string	no	-	Username for HTTP proxy authentication.	httpProxyUsername: "proxyuser"
spec.http.httpProxyUsernameFromEnv	string	no	-	Environment variable containing the HTTP proxy username.	httpProxyUsernameFromEnv: http_proxy_username
spec.http.httpProxyPassword	string	no	-	Password for HTTP proxy authentication.	httpProxyPassword: "s3cret"
spec.http.httpProxyPasswordFromEnv	string	no	-	Environment variable containing the HTTP proxy password.	httpProxyPasswordFromEnv: PROXY_PASSWORD
spec.r2	object	with type: r2	-	Cloudflare R2 authentication configuration.	r2: { accountId: abc123 }
spec.r2.keyId	string	no	-	R2 access key ID.	keyId: 1a2b3c
spec.r2.keyIdFromEnv	string	no	-	Environment variable containing the R2 access key ID.	keyIdFromEnv: R2_KEY_ID
spec.r2.secret	string	no	-	R2 secret access key.	secret: "abc123..."
spec.r2.secretFromEnv	string	no	-	Environment variable containing the R2 secret access key.	secretFromEnv: R2_SECRET
spec.r2.accountId	string	no	-	Cloudflare account ID.	accountId: 0a1b2c3d4e5f
spec.r2.endpoint	string	no	-	R2 endpoint URL.	endpoint: 0a1b2c3d4e5f.r2.cloudflarestorage.com
spec.azure	object	with type: azure	-	Azure Blob Storage authentication configuration (connection string or account name plus key).	azure: { connectionStringFromEnv: AZURE_STORAGE_CONNECTION_STRING }
spec.azure.connectionString	string	no	-	Azure storage connection string.	connectionString: "DefaultEndpointsProtocol=https;..."
spec.azure.connectionStringFromEnv	string	no	-	Environment variable containing the Azure connection string.	connectionStringFromEnv: AZURE_STORAGE_CONNECTION_STRING
spec.azure.accountName	string	no	-	Azure storage account name.	accountName: reportstorage
spec.azure.accountKey	string	no	-	Azure storage account key.	accountKey: "abc123..."
spec.azure.accountKeyFromEnv	string	no	-	Environment variable containing the Azure account key.	accountKeyFromEnv: AZURE_STORAGE_KEY
spec.huggingface	object	with type: huggingface	-	Hugging Face authentication configuration.	huggingface: { tokenFromEnv: HUGGINGFACE_TOKEN }
spec.huggingface.token	string	no	-	Hugging Face API token.	token: "hf_abc123..."
spec.huggingface.tokenFromEnv	string	no	-	Environment variable containing the Hugging Face token.	tokenFromEnv: HUGGINGFACE_TOKEN

See DataSource for how a secret is attached to a connection or a file path.