Configuration reference
Every scalar accepts the listed QOD_* / PROXY_* environment-variable override. Sensitive defaults (passwords, secrets, keys) are flagged; rotate them before any non-local deployment.
quack-flightsql
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-flightsql.host | PROXY_HOST | 0.0.0.0 | FlightSQL edge bind address. | |
quack-flightsql.port | PROXY_PORT | 31338 | FlightSQL edge port. | |
quack-flightsql.tlsEnabled | PROXY_TLS_ENABLED | true | Enable TLS on the FlightSQL edge. | |
quack-flightsql.tlsCertChain | PROXY_TLS_CERT_CHAIN | certs/server-cert.pem | Path to the TLS certificate chain PEM (auto-generated if missing). | |
quack-flightsql.tlsPrivateKey | PROXY_TLS_PRIVATE_KEY | certs/server-key.pem | Path to the TLS private key PEM (auto-generated if missing). | |
quack-flightsql.tenantClaim | PROXY_TENANT_CLAIM | tenant | JWT claim that carries the tenant identifier for routing. | |
quack-flightsql.sessionTtlSec | QOD_SESSION_TTL_SEC | 3600 | Edge session TTL in seconds before a fresh handshake is forced. |
quack-flightsql.acl
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-flightsql.acl.enabled | QOD_ACL_ENABLED | false | Enable table-level RBAC (per-statement EffectiveSet check). | |
quack-flightsql.acl.dialect | QOD_ACL_DIALECT | duckdb | Statement parser dialect for ACL extraction. |
quack-flightsql.auth
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-flightsql.auth.roleClaim | QOD_AUTH_ROLE_CLAIM | role | JWT claim that carries the user's role. | |
quack-flightsql.auth.database.enabled | QOD_AUTH_DB_ENABLED | true | Enable database (bcrypt) authentication for the FlightSQL edge. | |
quack-flightsql.auth.database.jdbcUrl | QOD_AUTH_DB_JDBC_URL | jdbc:postgresql://localhost:5432/qod | JDBC URL for the auth-lookup database. | |
quack-flightsql.auth.database.username | QOD_AUTH_DB_USER | postgres | Username for the auth-lookup JDBC connection. | |
quack-flightsql.auth.database.password | QOD_AUTH_DB_PASSWORD | *** | yes | Password for the auth-lookup JDBC connection. |
quack-flightsql.auth.database.query | QOD_AUTH_DB_QUERY | SELECT password_hash, role FROM qodstate_user WHERE (tenant IS NULL OR tenant = ?) AND username = ? ORDER BY (tenant IS NOT NULL) DESC LIMIT 1 | SQL template returning (password_hash, role); accepts three ? placeholders for tenant, pool, username. | |
quack-flightsql.auth.keycloak.enabled | QOD_AUTH_KEYCLOAK_ENABLED | false | Enable the Keycloak OIDC bearer provider. | |
quack-flightsql.auth.keycloak.baseUrl | QOD_AUTH_KEYCLOAK_BASE_URL | https://keycloak.example.com | Keycloak base URL (e.g. https://keycloak.example.com). | |
quack-flightsql.auth.keycloak.realm | QOD_AUTH_KEYCLOAK_REALM | quack | Keycloak realm name. | |
quack-flightsql.auth.keycloak.clientId | QOD_AUTH_KEYCLOAK_CLIENT_ID | (unset) | Keycloak client ID for ROPC. | |
quack-flightsql.auth.keycloak.clientSecret | QOD_AUTH_KEYCLOAK_CLIENT_SECRET | *** | yes | Keycloak client secret. |
quack-flightsql.auth.google.enabled | QOD_AUTH_GOOGLE_ENABLED | false | Enable the Google OIDC bearer provider. | |
quack-flightsql.auth.google.clientId | QOD_AUTH_GOOGLE_CLIENT_ID | (unset) | Google OAuth client ID. | |
quack-flightsql.auth.google.clientSecret | QOD_AUTH_GOOGLE_CLIENT_SECRET | *** | yes | Google OAuth client secret. |
quack-flightsql.auth.google.groupsLookup | QOD_AUTH_GOOGLE_GROUPS_LOOKUP | false | Resolve Google Workspace groups membership server-side. | |
quack-flightsql.auth.google.serviceAccountKeyPath | QOD_AUTH_GOOGLE_SVC_ACCT_KEY_PATH | (unset) | Path to a Google service-account JSON used for groups lookup. | |
quack-flightsql.auth.google.groupsCacheTtlSeconds | QOD_AUTH_GOOGLE_GROUPS_CACHE_TTL_SEC | 300 | Cache TTL for Google groups lookups in seconds. | |
quack-flightsql.auth.azure.enabled | QOD_AUTH_AZURE_ENABLED | false | Enable the Azure AD bearer provider. | |
quack-flightsql.auth.azure.tenantId | QOD_AUTH_AZURE_TENANT_ID | (unset) | Azure AD tenant ID. | |
quack-flightsql.auth.azure.clientId | QOD_AUTH_AZURE_CLIENT_ID | (unset) | Azure AD application (client) ID. | |
quack-flightsql.auth.azure.clientSecret | QOD_AUTH_AZURE_CLIENT_SECRET | *** | yes | Azure AD application client secret. |
quack-flightsql.auth.aws.enabled | QOD_AUTH_AWS_ENABLED | false | Enable the AWS Cognito bearer provider. | |
quack-flightsql.auth.aws.region | QOD_AUTH_AWS_REGION | us-east-1 | AWS region hosting the Cognito user pool. | |
quack-flightsql.auth.aws.userPoolId | QOD_AUTH_AWS_USER_POOL_ID | (unset) | Cognito user pool ID. | |
quack-flightsql.auth.aws.clientId | QOD_AUTH_AWS_CLIENT_ID | (unset) | Cognito app client ID. | |
quack-flightsql.auth.jwt.secretKey | JWT_SECRET_KEY | *** | yes | HMAC secret for HS256/HS512 external JWT verification. |
quack-flightsql.auth.jwt.publicKeyPath | JWT_PUBLIC_KEY_PATH | (unset) | Path to the RSA/ECDSA PEM public key for external JWT verification. | |
quack-flightsql.auth.jwt.issuer | JWT_ISSUER | (unset) | Expected 'iss' claim value (empty = not checked). | |
quack-flightsql.auth.jwt.audience | JWT_AUDIENCE | (unset) | Expected 'aud' claim value (empty = not checked). | |
quack-flightsql.auth.oauth.enabled | QOD_AUTH_OAUTH_ENABLED | false | Enable the browser-based OAuth (auth-code grant) flow. | |
quack-flightsql.auth.oauth.port | QOD_AUTH_OAUTH_PORT | 8888 | Local port the OAuth callback server listens on. | |
quack-flightsql.auth.oauth.baseUrl | QOD_AUTH_OAUTH_BASE_URL | http://localhost:8888 | Externally-reachable base URL for OAuth callbacks. | |
quack-flightsql.auth.oauth.scopes | QOD_AUTH_OAUTH_SCOPES | openid profile email | OAuth scopes requested at authorization time. | |
quack-flightsql.auth.oauth.sessionTimeoutSeconds | QOD_AUTH_OAUTH_SESSION_TIMEOUT_SEC | 3600 | OAuth-session timeout in seconds. | |
quack-flightsql.auth.oauth.disableTls | QOD_AUTH_OAUTH_DISABLE_TLS | false | Disable TLS on the OAuth callback server (dev only). |
quack-flightsql.validation
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-flightsql.validation.enabled | QOD_VALIDATION_ENABLED | true | Enable per-statement SQL validation. | |
quack-flightsql.validation.allowByDefault | QOD_VALIDATION_ALLOW_BY_DEFAULT | true | When true, statements pass when no explicit rule matches. | |
quack-flightsql.validation.bypassUsers | QOD_VALIDATION_BYPASS_USERS | admin@localhost.local,admin | Comma-separated usernames that skip SQL validation entirely. |
quack-on-demand
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.host | QOD_ON_DEMAND_HOST | 0.0.0.0 | Manager REST bind address (0.0.0.0 to listen on all interfaces). | |
quack-on-demand.port | QOD_ON_DEMAND_PORT | 20900 | Manager REST + admin UI port. | |
quack-on-demand.apiKey | QOD_API_KEY | *** | yes | Static admin API key sent as X-API-Key. Unset = REST namespace is open. |
quack-on-demand.runtimeType | QOD_RUNTIME_TYPE | local | Quack node runtime backend: 'local' (child processes) or 'kubernetes'. | |
quack-on-demand.minPort | QOD_MIN_PORT | 21900 | Lower bound of the port range LocalQuackBackend allocates child nodes from. | |
quack-on-demand.maxPort | QOD_MAX_PORT | 22500 | Upper bound of the port range LocalQuackBackend allocates child nodes from. | |
quack-on-demand.maxNodesTotal | QOD_MAX_NODES_TOTAL | 50 | Hard cap on concurrent child nodes across all pools. | |
quack-on-demand.statePath | QOD_STATE_PATH | ./state/quack-on-demand-state.json | File-mode state path (only used when stateStorage=file). | |
quack-on-demand.stateStorage | QOD_STATE_STORAGE | postgres | Control-plane store: 'postgres' (qodstate_* tables) or 'file' (JSON blob). | |
quack-on-demand.nativeClient | QOD_NATIVE_CLIENT | true | Use the JNI-backed native Quack wire client. False falls back to the embedded path. | |
quack-on-demand.nodeDisableSsl | QOD_NODE_DISABLE_SSL | true | Disable TLS on the embedded path's quack_query() call. Ignored on the native path. | |
quack-on-demand.spawnScript | QOD_SPAWN_SCRIPT | ./scripts/spawn-quack-node.sh | Path to spawn-quack-node.sh invoked by LocalQuackBackend. | |
quack-on-demand.drainTimeoutSec | QOD_DRAIN_TIMEOUT_SEC | 60 | Seconds to wait for in-flight statements during graceful pool shutdown. | |
quack-on-demand.healthCheckIntervalSec | QOD_HEALTH_CHECK_INTERVAL_SEC | 5 | Seconds between supervisor health checks against child nodes. |
quack-on-demand.admin
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.admin.username | QOD_ADMIN_USERNAME | admin@localhost.local,admin | Comma-separated admin usernames seeded into qodstate_user. | |
quack-on-demand.admin.password | QOD_ADMIN_PASSWORD | *** | yes | Bootstrap admin password (re-hashed on every boot). |
quack-on-demand.admin.role | QOD_ADMIN_ROLE | admin | Role assigned to the bootstrap admin user. |
quack-on-demand.auth
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.auth.management.identitySource | QOD_AUTH_MANAGEMENT_IDENTITY_SOURCE | db | Management-plane identity source: 'db' (qodstate_user as identity+authz) or 'oidc' (IdP for identity, qodstate_user for role+tenants). | |
quack-on-demand.auth.management.identityClaim | QOD_AUTH_MANAGEMENT_IDENTITY_CLAIM | preferred_username | JWT claim matched against qodstate_user.username when identitySource=oidc (email is tried as a fallback). |
quack-on-demand.bootstrap
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.bootstrap.enabled | QOD_BOOTSTRAP_ENABLED | true | Auto-create starter tenant + pool on boot. Idempotent. | |
quack-on-demand.bootstrap.tenant | QOD_BOOTSTRAP_TENANT | tpch | Tenant name seeded at boot. | |
quack-on-demand.bootstrap.tenantDb | QOD_BOOTSTRAP_TENANTDB | tpch1 | Tenant-db suffix; actual DB is ${tenant}_${tenantDb}. | |
quack-on-demand.bootstrap.pool | QOD_BOOTSTRAP_POOL | sales | Pool name seeded at boot. | |
quack-on-demand.bootstrap.roleDistribution.writeonly | QOD_BOOTSTRAP_WRITEONLY | 1 | Number of WRITEONLY nodes in the bootstrap pool. | |
quack-on-demand.bootstrap.roleDistribution.readonly | QOD_BOOTSTRAP_READONLY | 1 | Number of READONLY nodes in the bootstrap pool. | |
quack-on-demand.bootstrap.roleDistribution.dual | QOD_BOOTSTRAP_DUAL | 1 | Number of DUAL nodes in the bootstrap pool. |
quack-on-demand.defaultMetastore
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.defaultMetastore.pgHost | QOD_PG_HOST | localhost | Postgres host for control plane + DuckLake catalog. | |
quack-on-demand.defaultMetastore.pgPort | QOD_PG_PORT | 5432 | Postgres port. | |
quack-on-demand.defaultMetastore.pgUser | QOD_PG_USER | postgres | Postgres username used by the manager + Quack nodes. | |
quack-on-demand.defaultMetastore.pgPassword | QOD_PG_PASSWORD | *** | yes | Postgres password. |
quack-on-demand.defaultMetastore.dbName | QOD_PG_DBNAME | qod | Control-plane database name (default 'qod'). | |
quack-on-demand.defaultMetastore.schemaName | QOD_PG_SCHEMA | main | Postgres schema for control-plane tables. | |
quack-on-demand.defaultMetastore.dataPath | QOD_DUCKLAKE_DATA_PATH | ./ducklake/tpch | Root path for DuckLake parquet data files. |
quack-on-demand.federation
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.federation.secretStore | QOD_FEDERATION_SECRET_STORE | dispatch | Federation secret resolver: postgres | env | aws-sm | gcp-sm | azure-kv | vault. |
quack-on-demand.k8s
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.k8s.namespace | QOD_K8S_NAMESPACE | default | Kubernetes namespace KubernetesQuackBackend operates in. | |
quack-on-demand.k8s.image | QOD_K8S_IMAGE | starlakeai/quack-on-demand-node:latest-snapshot | Docker image used for spawned Quack-node pods. | |
quack-on-demand.k8s.serviceAccount | QOD_K8S_SERVICE_ACCOUNT | (unset) | ServiceAccount applied to spawned node pods (unset = default). | |
quack-on-demand.k8s.serviceType | QOD_K8S_SERVICE_TYPE | ClusterIP | Kubernetes Service type fronting node pods. | |
quack-on-demand.k8s.quackPort | QOD_K8S_QUACK_PORT | 8080 | Container port exposing each node's /quack endpoint. | |
quack-on-demand.k8s.startupTimeoutSec | QOD_K8S_STARTUP_TIMEOUT_SEC | 120 | Seconds to wait for a spawned node pod to become ready. | |
quack-on-demand.k8s.podLabel | QOD_K8S_POD_LABEL | managed-by=quack-on-demand | Label selector that identifies manager-owned node pods. |
quack-on-demand.metrics
| Key | Env var | Default | Sensitive | Description |
|---|---|---|---|---|
quack-on-demand.metrics.sink | QOD_METRICS_SINK | prometheus | Active metrics sink: prometheus | aws | azure | gcp | none. | |
quack-on-demand.metrics.aws.namespace | QOD_METRICS_AWS_NAMESPACE | quack-on-demand | CloudWatch namespace when metrics.sink=aws. | |
quack-on-demand.metrics.aws.stepSeconds | QOD_METRICS_AWS_STEP_SEC | 60 | CloudWatch publish step in seconds. | |
quack-on-demand.metrics.azure.instrumentationKey | QOD_METRICS_AZURE_KEY | *** | yes | Azure Monitor instrumentation key. |
quack-on-demand.metrics.azure.stepSeconds | QOD_METRICS_AZURE_STEP_SEC | 60 | Azure Monitor publish step in seconds. | |
quack-on-demand.metrics.gcp.projectId | QOD_METRICS_GCP_PROJECT_ID | (unset) | GCP project ID when metrics.sink=gcp. | |
quack-on-demand.metrics.gcp.stepSeconds | QOD_METRICS_GCP_STEP_SEC | 60 | GCP Cloud Monitoring publish step in seconds. |