database

The one required section. Which engine, where it is, and how to authenticate. A URL hydrates host, port and database; you can still set username, password and schema alongside it. Engine-specific keys are documented on each engine page.

Two ways to write it

yaml

# As a URL
database:
  type: postgresql
  url: "postgresql://db.internal:5432/app"
  username: "vault://secret/data/app#db_user"
  password: "vault://secret/data/app#db_password"

# Or as parts
database:
  type: postgresql
  host: db.internal
  port: 5432
  database: app
  schema: "public"
  connection_timeout: 30

Keys

Key	Default	What it does
`type`	—	The engine key. Required unless the URL carries it. See the capability matrix for every accepted value.
`url`	`""`	Full connection URL. Given this, `host`, `port` and `database` are unnecessary.
`host`	—	Server hostname, when you assemble the connection from parts instead.
`port`	—	Server port. Read as an integer.
`database`	—	Database name on that server.
`username`	`""`	Login name. Prefer an environment variable or a secret URI over a literal.
`password`	`""`	Password. The same applies, more so — a literal here ends up in version control.
`schema`	`""`	Default schema for unqualified objects. What this means varies by engine.
`connection_timeout`	`30`	Seconds to wait for a connection before giving up.
`installed_by`	—	Name recorded against migrations applied on this connection, instead of the database user.
`extra_params`	`{}`	Driver parameters appended to the connection URL.
`properties`	`{}`	Engine-specific connection properties.
`options`	`{}`	Options passed to the driver when it opens the connection.
`session_variables`	`{}`	Variables set on every session DBLift opens.
`fail_on_fixed_dbo`	`false`	SQL Server only. See the SQL Server page.

A key under database: that no engine recognises is ignored, and a warning names the key. Put a genuine driver option under extra_params. A key that is a valid field of another engine, or an internal key whose name starts with _, is ignored without that warning. Values are not included in the warning.

Environment variables and CLI overrides

When the same setting is given twice, the higher source wins: CLI flag, then environment variable, then dblift.yaml. The full order, including environment blocks, is on Configuration.

Connection settings follow DBLIFT_DB_<FIELD> for database.<field>. Both DBLIFT_DB_USER and DBLIFT_DB_USERNAME set database.username.

Setting	`dblift.yaml` key	Environment variable	CLI flag
Connection URL	`database.url`	`DBLIFT_DB_URL`	`--db-url`
Engine type	`database.type`	`DBLIFT_DB_TYPE`	—
Host	`database.host`	`DBLIFT_DB_HOST`	—
Port	`database.port`	`DBLIFT_DB_PORT`	—
Database name	`database.database`	`DBLIFT_DB_DATABASE`	—
Username	`database.username`	`DBLIFT_DB_USERNAME` / `DBLIFT_DB_USER`	`--db-username`
Password	`database.password`	`DBLIFT_DB_PASSWORD`	`--db-password`
Schema	`database.schema`	`DBLIFT_DB_SCHEMA`	`--db-schema`
Connection timeout	`database.connection_timeout`	`DBLIFT_DB_CONNECTION_TIMEOUT`	—

DBLIFT_DB_URL is enough on its own — no config file needed.

export DBLIFT_DB_URL="postgresql+psycopg://localhost:5432/mydb"
export DBLIFT_DB_PASSWORD="s3cret"
dblift migrate

dblift migrate --db-url "postgresql+psycopg://staging:5432/mydb"

Booleans (encrypt, trust_server_certificate, integrated_security, use_managed_identity, and SQL Server fail_on_fixed_dbo as DBLIFT_DB_FAIL_ON_FIXED_DBO), structured maps (options, session_variables, extra_params, properties), and Cosmos fields (account_endpoint, account_key, database_name, container_name) use the same DBLIFT_DB_* convention. 1, true, and yes count as true. The full DBLIFT_* list is on Configuration. Prefer a secret URI or an environment variable over a literal password — see secrets.

Keep credentials out of the file

Any string field can hold a secret URI instead of a literal, or be left out entirely and supplied as DBLIFT_DB_PASSWORD. Credentials are masked wherever DBLift prints a connection back to you.

PreviousOverview & precedence Nextmigrations