Configuration reference

Everything in pgevolve.toml. The capability spec lists what's implemented vs. planned; this file walks through how to use what's implemented today.

pgevolve init creates a minimal config; this guide explains each section.

File location

By default pgevolve loads ./pgevolve.toml. Override with --config <path> on any command.

[project]

[project]
name           = "myapp"            # informational
schema_dir     = "schema"           # relative to the config file
plan_dir       = "plans"            # relative to the config file
layout_profile = "schema-mirror"    # one of the built-ins, or a path

[managed]

[managed]
schemas        = ["app", "billing"]
ignore_objects = ["app.legacy_etl_*", "billing.audit_*"]

The [managed] filter is the safety net. Even if your source tree declares only one table, an unfiltered apply would emit drops for every catalog object outside your control. The filter prevents that.

[planner]

[planner]
strategy = "online"   # "atomic" | "online"

[planner.online_rewrites]

[planner.online_rewrites]
create_index_concurrent       = true
fk_not_valid_then_validate    = true
check_not_valid_then_validate = true
not_null_via_check_pattern    = true
refresh_mv_concurrently       = true
view_drop_create_dependents   = true

Each switch defaults to true. Setting any to false disables that specific rewrite without dropping to atomic mode. Useful for environments where you want online behavior in general but need to opt out of one pattern (e.g., a managed-service Postgres that disallows CONCURRENTLY).

[environments.<name>]

[environments.dev]
url      = "postgres://localhost/myapp_dev"

[environments.prod]
url_env  = "DATABASE_URL_PROD"        # read DSN from env var (recommended)
strategy = "online"                   # overrides [planner].strategy for --db=prod

[environments.test]
url      = "postgres://localhost/myapp_test"
strategy = "atomic"                   # opt-out for fast / hermetic test DB

Omit both url and url_env to fall through to PGEVOLVE_DATABASE_URL and libpq env vars (PGHOST, PGUSER, etc.).

Connection precedence

For pgevolve <cmd> --db <env>:

1. --url <dsn> (CLI argument)
2. [environments.<env>].url
3. [environments.<env>].url_env
4. PGEVOLVE_DATABASE_URL
5. libpq env vars
6. ~/.pgpass

[shadow]

[shadow]
backend          = "auto"         # auto | testcontainers | dsn
url              = "postgres://localhost/myapp_shadow"   # for backend = "dsn"
url_env          = "PGEVOLVE_SHADOW_URL"                 # alternative to url
reset            = "drop_schema_cascade"                 # drop_schema_cascade | none
extensions       = ["pgcrypto", "uuid-ossp"]
postgres_version = "17"           # major version; used to select container or validate DSN

backend values

• "auto" (default): uses url / url_env if set; otherwise tries testcontainers if Docker is available; otherwise errors with a helpful message.
• "testcontainers": always uses Docker. Hermetic; requires Docker to be running. Pulls postgres:<major>-alpine.
• "dsn": connects to a user-supplied Postgres. No Docker required. Useful for developers without Docker or for projects with pre-installed extensions (TimescaleDB, PostGIS, etc.).

pgevolve validate --shadow and the --shadow-validate flag on plan / diff / validate all read this block. Without it those flags error out with a helpful message.

[[lint_waiver]]

[[lint_waiver]]
rule   = "column-position-drift"
target = "app.users"
reason = "applied via separate rewrite-table operation; see PR #234"

[[lint_waiver]] rows acknowledge LintAtPlan-severity findings so that pgevolve plan doesn't refuse with exit 2. Live in the plan's intent.toml, not in pgevolve.toml.

Match semantics: a waiver applies when rule equals the finding's rule name and target is a substring of the finding's message. A waiver that matches zero findings is reported as a warning ("unused waiver").

Preflight at apply time validates structural well-formedness: both rule and target must be non-empty strings. A malformed waiver row causes preflight to exit 2.

Multiple [[lint_waiver]] rows are supported — use one per finding.

[cluster]

[cluster]
project = "../my-cluster"

Optional. Links this per-DB project to a sibling cluster project (managed via pgevolve cluster … against a pgevolve-cluster.toml). When set, cluster-aware lints (e.g. grant-references-unknown-role) cross-check grantee role names against the linked cluster project's declared roles.

See docs/spec/cluster.md for the cluster surface and docs/spec/grants.md for the cross-check rules.

Worked example: production-grade config

[project]
name           = "ledger"
schema_dir     = "schema"
plan_dir       = "plans"
layout_profile = "schema-mirror"

[managed]
schemas        = ["app", "billing", "audit"]
ignore_objects = ["audit.legacy_*"]

[planner]
strategy = "online"

[planner.online_rewrites]
# Production DB doesn't allow CONCURRENTLY (RDS-style).
create_index_concurrent       = false
fk_not_valid_then_validate    = true
check_not_valid_then_validate = true
not_null_via_check_pattern    = true

[environments.dev]
url      = "postgres://localhost/ledger_dev"
strategy = "atomic"               # fast local iteration

[environments.staging]
url_env  = "DATABASE_URL_STAGING"

[environments.prod]
url_env  = "DATABASE_URL_PROD"

[shadow]
backend          = "testcontainers"
postgres_version = "16"

CI runs pgevolve validate --shadow on every PR. The dev developer runs pgevolve plan --db dev, then pgevolve plan --db staging once the diff stabilizes; the same plan directory is applied to staging and production after intent-file approval.