pgevolve

Postgres-specific declarative schema management.

pgevolve treats a directory of CREATE-style SQL files as the source of truth for one or more Postgres schemas, introspects a live database to derive its current state, and computes ordered, dependency-aware migration plans that bring the database to the desired state. It refuses to lose data unless explicitly authorized in a per-plan intent file.

Status: v0.3.3 is the current release. The v0.2 sub-spec series (views/MVs, types, extensions, functions/procedures, triggers, declarative partitioning) is complete, and the v0.3 cross-cutting state series (cluster roles, GRANT/REVOKE, row-level security, table/index/MV storage parameters) is complete through v0.3.3. See CHANGELOG.md for what's in each version.

Install

From crates.io (recommended):

cargo install pgevolve

From source:

git clone https://github.com/saosebastiao/pgevolve
cd pgevolve
cargo install --path crates/pgevolve

pgevolve requires Rust 1.95+.

Usage at a glance

# 1. Scaffold a project (creates `pgevolve.toml`, `schema/`, `plans/`).
pgevolve init

# 2. Author your schema as CREATE-style SQL under `schema/`.
#    File layout is enforced by the `layout_profile` setting; the default
#    (`schema-mirror`) wants `schema/<schema>/<kind>/<name>.sql`.

# 3. Plan a migration against a configured environment.
pgevolve plan --db dev
#   wrote plans/2026-05-12-<short-id>/{plan.sql, intent.toml, manifest.toml}

# 4. Review the generated plan.sql + intent.toml in code review.

# 5. Apply it.
pgevolve apply plans/2026-05-12-<short-id> --db dev

CLI surface

Exit codes follow spec §13: 0 success, 1 lint/validation error, 2 drift or pre-flight mismatch, 3 apply error, 4 config or CLI input error.

Configuration

pgevolve.toml:

[project]
name           = "myapp"
schema_dir     = "schema"
plan_dir       = "plans"
layout_profile = "schema-mirror"          # also: kind-grouped | feature-grouped | free-form | <path-to-custom.toml>

[managed]
schemas        = ["app", "billing"]       # schemas under pgevolve's control
ignore_objects = ["app.legacy_etl_*"]     # qname or glob

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

[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

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

[environments.prod]
url_env  = "DATABASE_URL_PROD"            # read DSN from env var
strategy = "online"

Connection precedence (mirrors psql): --url CLI flag → [environments.<env>].url → [environments.<env>].url_env → PGEVOLVE_DATABASE_URL → libpq env (PGHOST, PGUSER, ...).

Documentation

• docs/user/ — user guide: installation, getting started, configuration reference, command reference, cookbook, troubleshooting, plan-format walkthrough. Start here if you're operating pgevolve on a project.
• docs/system/ — architecture and internals: the dedicated architecture chapter, deep dives on the IR, planner, and executor. Start here if you want to understand how pgevolve works under the hood.
• docs/spec/ — living capability catalogue: every object kind, column type, constraint, index option, CLI command, etc., with its implementation status (Implemented / Partial / Planned / Future / Not planned). Start here to find out whether pgevolve does / will do a given thing.
• docs/superpowers/specs/2026-05-09-pgevolve-design.md — original v0.1 design doc.
• docs/superpowers/plans/ — phase-by-phase implementation plans.

v0.1 phase progress

v0.2 sub-spec progress

Per the arch-readiness spec §16, v0.2 ships as a sequence of per-object-family sub-specs on the v0.2-readiness foundation.

v0.3 sub-spec progress

v0.3 ships the cross-cutting state series: each release adds a new dimension of state that attaches to existing IR objects (rather than introducing new object kinds). All four sub-specs share the same design pattern — typed Option<T> fields with a lenient drift policy: source None means "unmanaged, never reset," surfaced via per-feature unmanaged-* lints rather than destructive changes.

Next on the agreed v0.3 roadmap: PUBLICATION / SUBSCRIPTION (logical replication), CREATE VIEW WITH CHECK OPTION, aggregates, and CREATE STATISTICS.

v0.2 views/MVs — what's in 0e2a7a0

v0.2 types — what's in 6127bdd

v0.2 extensions — what's in c17b3bc..8522c95

v0.2 functions and procedures — what's in 3c3f6ee

v0.2 triggers — what's in 25ca3a5

v0.2 partitioning — what's in fbff481

Workspace layout

• crates/pgevolve-core — IR, parser, diff, planner, plan I/O, lint engine. Pure library; no I/O at the type level (the parser owns the only filesystem walk).
• crates/pgevolve — CLI binary + executor. Holds the tokio_postgres adapter, advisory lock, audit writers, and the apply loop.
• crates/pgevolve-testkit — internal test infra: EphemeralPostgres (testcontainers wrapper), PgCatalogQuerier, IR generator and mutator, equivalence asserter, migration-fixture loader.
• crates/pgevolve-conformance — deterministic fixture-driven conformance suite: one directory per fixture, asserts diff / plan / plan.sql golden / apply roundtrip. New goldens via cargo xtask bless --conformance.
• xtask — cargo xtask bless regenerates tier-3 catalog goldens.

Test tiers

Tier C is the canonical CI gate; every deterministic correctness expectation lives there as a fixture. Fixture authoring subtrees under crates/pgevolve-conformance/tests/cases/:

Layers L1–L9 within each fixture:

Backend selection for Docker-gated layers: set PGEVOLVE_TEST_PG_MODE=testcontainers|compose|dsn.

• testcontainers (default) — pulls postgres:<major>-alpine.
• compose — connects to a running container started by dev/docker-compose.pg.yml (faster in local dev).
• dsn — connects to an explicit DSN from PGEVOLVE_TEST_PG_URL.

Set PGEVOLVE_DISABLE_DOCKER_TESTS=1 to skip every Docker-gated test; the suite skips cleanly when docker info fails.

Regenerate tier-3 catalog goldens with cargo xtask bless (runs against ephemeral containers per PG major). Regenerate tier-C conformance goldens with cargo xtask bless --conformance.

Dependencies

The workspace deliberately avoids unmaintained / archived crates. Notable choices:

• Parsing: pg_query (official Postgres parser bindings).
• Hashing: blake3 — plan id, target identity, and IR canonical hashing.
• Encoding: bincode for the plan-id input hash payload (binary & deterministic), serde_json for the embedded catalog snapshot in manifest.toml. serde_yaml is deliberately not used (upstream archived it in 2024).
• CLI: clap v4 derive.
• Async runtime: tokio multi-thread; tokio-postgres for the executor.
• Property tests: proptest v1, with EphemeralPostgres from testcontainers for tier-4/5.

License

Dual-licensed under MIT or Apache-2.0, at your option.

License + dependency policy

pgevolve is dual-licensed under MIT or Apache-2.0. All dependencies must be MIT/Apache-2.0/BSD-style licensed (no copyleft); the policy is enforced by cargo deny check (see deny.toml) and verified in CI. Only permissive licenses are allowed: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unicode-DFS-2016, Unicode-3.0, CC0-1.0, and Zlib. Vulnerable and yanked crates are denied; the check enforces that all dependencies come from crates.io.