Named Environments

import { Aside } from ‘@astrojs/starlight/components’;

Run the same project against dev, staging, and prod without juggling flags. Define each environment once in workflow_settings.yaml — its schema suffix, vars, and its own credentials file — and select it with --environment <name> on compile, run, or test.

Why not just --schema-suffix? A schema suffix only renames output schemas — it can’t point at a different database or credentials. Prod and staging usually differ by more than a name. A named environment bundles the suffix and the connection; --schema-suffix stays the low-level primitive.

Define environments

Add an environments: map to workflow_settings.yaml. It holds only non-secret overrides plus a pointer to each environment’s credentials file — never the secrets themselves:

warehouse: postgres
defaultDataset: analytics

environments:
  dev:
    schemaSuffix: dev                      # output schemas get a _dev suffix
    credentials: .df-credentials.dev.json
  prod:
    defaultDatabase: prod_db
    vars:
      region: us-prod
    credentials: .df-credentials.prod.json

Field	Effect
`schemaSuffix`	Appends `_<suffix>` to every output schema (same as `--schema-suffix`)
`vars`	Variables for `${sqlanvil.projectConfig.vars.…}` (merged per-key)
`defaultDatabase`	Overrides the default database / BigQuery project
`defaultLocation`	Overrides the default location (BigQuery)
`credentials`	Path (relative to the project dir) to this environment’s credentials file

Use an environment

sqlanvil run . --environment prod
# loads prod's overrides (defaultDatabase, vars) AND its credentials file

--environment works on compile, run, and test. compile applies the config overrides; run/test additionally connect with the environment’s credentials.

Precedence

Explicit CLI flag > environment > workflow_settings defaults. An explicit flag always wins, so you can override one piece ad hoc:

sqlanvil run . --environment dev --schema-suffix qa
# dev's credentials + vars, but the schema suffix is qa

vars merge per-key — a --vars key overrides that key from the environment, which overrides workflow_settings; other keys are preserved.
Credentials: explicit --credentials <path> > the environment’s credentials > the default .df-credentials.json.

Errors

--environment <name> with no matching entry fails fast: Environment "<name>" not found. Available environments: ….
--environment with no environments: block: No environments defined in workflow_settings.yaml.