Configuration

One file describes the database, where migrations live, and how each environment differs. Nothing in it is required except the database — every other section has a working default.

Where configuration comes from

DBLift needs at least one source. Pass a file, pass a URL, or set one environment variable — any of the three is enough on its own.

dblift --config ./dblift.yaml info
dblift --db-url "postgresql://localhost:5432/mydb" info
export DBLIFT_DB_URL="postgresql://localhost:5432/mydb"

No configuration source provided

Pass --config, --db-url, or set DBLIFT_DB_URL.

The sections

Section	Edition	What it covers
`database`	OSS	Which engine, where it lives, and how to authenticate. The only required section.
`migrations`	OSS	Where migration files are found, how they are named, and which ones a run considers.
`logging`	OSS	Level, destination file or directory, and output format.
`secrets`	OSS	Where credentials are read from, so they never sit in the file.
`environments`	OSS	Named overlays on everything above. Selected with `--env` or `DBLIFT_ENV`.
`validation`	Pro / Enterprise	Thresholds and a custom `rules_file` on Pro. Named profiles and the built-in packs beyond `security` on Enterprise.
`data_sets`	Pro / Enterprise	Named sets of audited DML. `data new`/`plan`/`apply`/`status` are Pro; undo and capture are Enterprise.
`zero_downtime`	Pro / Enterprise	Backfill settings, `enforce`, and `allow_drops`. Table and column drops also need `--approved-by`.

Root keys

A handful of settings sit at the top level rather than inside a section.

Key	Default	What it does
`history_table`	`dblift_schema_history`	Table that records every applied migration.
`snapshot_table`	`dblift_schema_snapshots`	Table that stores captured schema snapshots.
`max_snapshots`	—	How many snapshots to retain before the oldest is dropped.
`strict_mode`	`false`	Enforces Flyway-compatible strict validation rules.
`clean_disabled`	`true`	Guards `dblift clean`. Must be turned off deliberately before it will run.
`placeholders`	`{}`	Values substituted into SQL at apply time.
`installed_by`	—	Name written to the Installed By column instead of the database user.

Precedence

When the same setting is given twice, the higher source wins. Nothing is merged field by field except the environment block, which overlays the root sections.

Order	Source	Notes
1	CLI flag	Highest. Wins over everything below.
2	Environment variable	Any recognised `DBLIFT_*` name.
3	Environment block	The selected block under `environments:`.
4	Root section	The shared base.
5	Built-in default	What you get having said nothing.

Which environment block is selected is itself resolved in order: --env, then DBLIFT_ENV, then a branch map if you have configured one, then none.

Environment variables

Connection settings follow one convention: DBLIFT_DB_<FIELD> sets database.<field>. The accepted names are an explicit list — an unrecognised one is ignored rather than applied, so an unrelated CI variable can never shadow a real setting.

Variable	Sets
`DBLIFT_ENV`	Selects the environment block. Overridden by `--env`; the variable name itself can be changed with `resolve.env_var`.
`DBLIFT_DB_URL`	Full connection URL. Enough on its own — no config file needed.
`DBLIFT_DB_TYPE`	Engine key, when the URL does not carry it.
`DBLIFT_DB_HOST` / `_DATABASE` / `_SCHEMA` / `_INSTANCE`	Connection parts, if you would rather not assemble a URL.
`DBLIFT_DB_USER` / `_USERNAME` / `_PASSWORD`	Credentials. Both user spellings map to the same field.
`DBLIFT_DB_PORT` / `_CONNECTION_TIMEOUT`	Read as integers. A non-numeric value is reported, not silently dropped.
`DBLIFT_DB_ENCRYPT` / `_TRUST_SERVER_CERTIFICATE` / `_INTEGRATED_SECURITY` / `_USE_MANAGED_IDENTITY`	Booleans — `true`, `1` and `yes` all count as true.
`DBLIFT_DB_OPTIONS` / `_SESSION_VARS` / `_EXTRA_PARAMS` / `_PROPERTIES`	Structured values, given as JSON or comma-separated `key=value` pairs.
`DBLIFT_DB_ACCOUNT_ENDPOINT` / `_ACCOUNT_KEY` / `_DATABASE_NAME` / `_CONTAINER_NAME`	Azure Cosmos DB connection fields.
`DBLIFT_HISTORY_TABLE` / `DBLIFT_SNAPSHOT_TABLE` / `DBLIFT_MAX_SNAPSHOTS`	The three root keys that can be set from the environment.

PreviousEditions & tiers Nextdatabase