Environment Variables

On this page

Load secrets and config from .env in the project root. System environment variables override .env.

Access

Context	Syntax
SQL config files	`${VAR}`
Starlark scripts	`env.get("VAR")`
Starlark write	`env.set("VAR", "value")`

.env Syntax

KEY=VALUE
KEY="quoted value"
KEY='single quoted'
# comments ignored

OndatraSQL Variables

Variable	Description
`ONDATRA_STATE_KEY`	Base64-encoded 32-byte key for file-level encryption of the state catalog. Generated by `ondatrasql init` and written to `.env`. Required when `config/state.sql` uses `ENCRYPTION_KEY '${ONDATRA_STATE_KEY}'` (the default). Lose it and the state file becomes unreadable — keep a backup separately.
`EDITOR`	Editor for `ondatrasql edit` (falls back to nano, vi, vim)

OAuth2 Provider Variables

Provider name maps to an env prefix: google-sheets becomes GOOGLE_SHEETS_*. (The hosted-broker flow via ONDATRA_KEY / oauth2.ondatra.sh was removed in v0.36.0.) Two ways to authenticate, checked in this order:

1. Injected access token — if set, used directly; ondatrasql does no consent, refresh, or token storage. For setups where an orchestrator or secrets manager (e.g. OpenBao) owns the OAuth lifecycle and hands a fresh access token per run.

Variable Description

ONDATRA_OAUTH_TOKEN_<PREFIX> Pre-obtained OAuth2 access token; sent as Authorization: Bearer. <PREFIX> is the provider upper-cased with -→_ — so google-sheets → ONDATRA_OAUTH_TOKEN_GOOGLE_SHEETS. Takes precedence over the local flow. The caller refreshes it between runs and must inject a token whose lifetime covers the run — for runs longer than the provider’s token TTL, use the local flow instead. A whitespace-only value is treated as unset.

Variable	Description
`ONDATRA_OAUTH_TOKEN_<PREFIX>`	Pre-obtained OAuth2 access token; sent as `Authorization: Bearer`. `<PREFIX>` is the provider upper-cased with `-`→`_` — so `google-sheets` → `ONDATRA_OAUTH_TOKEN_GOOGLE_SHEETS`. Takes precedence over the local flow. The caller refreshes it between runs and must inject a token whose lifetime covers the run — for runs longer than the provider’s token TTL, use the local flow instead. A whitespace-only value is treated as unset.

2. Self-contained local flow — your own app credentials; ondatrasql auth <provider> does browser consent and stores the refresh token in the encrypted state catalog, refreshed in-process.

Variable	Description
`<PREFIX>_CLIENT_ID`	OAuth2 client ID
`<PREFIX>_CLIENT_SECRET`	OAuth2 client secret
`<PREFIX>_AUTH_URL`	Authorization endpoint
`<PREFIX>_TOKEN_URL`	Token endpoint
`<PREFIX>_SCOPE`	OAuth2 scopes (required)

Cloud Storage

Picked up automatically by DuckDB’s credential chain.

Variable	Provider
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`	Amazon S3
`GOOGLE_APPLICATION_CREDENTIALS`	Google Cloud Storage
`AZURE_STORAGE_ACCOUNT`, `AZURE_STORAGE_KEY`	Azure Blob Storage