Plan format

A plan directory is the unit of code review. This guide explains what each file means and how the executor consumes it.

plans/2026-05-11-abc1234567890123/
├── plan.sql        ← canonical artifact (commit this)
├── intent.toml     ← destructive approvals (commit this; flip approvals when ready)
└── manifest.toml   ← plan id, version metadata, embedded pre-image (commit this)

All three files are plain text. Commit them to the same repo as your schema/ tree — the plan directory is part of the migration history.

plan.sql

The applyable artifact. Reads cleanly with psql -f plan.sql for people who want to bypass the executor — pgevolve only relies on the structured -- @pgevolve directive comments to drive transactions and audit logging.

Header directives

-- @pgevolve plan id=abc1234567890123 version=0.3.3 ruleset=1 created=2026-05-11T18:42:11Z
-- @pgevolve source_rev=git:c0ffeeabc
-- @pgevolve target=tid-xyz
-- @pgevolve intents_required=2

Group and step directives

Each transactional group is wrapped in BEGIN; ... COMMIT;. Each step has its own directive line:

-- @pgevolve group id=1 transactional=true
BEGIN;
-- @pgevolve step=1 kind=create_table destructive=false targets=app.invoices
CREATE TABLE app.invoices ( ... );
-- @pgevolve step=2 kind=add_constraint_not_valid destructive=false targets=app.invoices.invoices_customer_fk
ALTER TABLE app.invoices ADD CONSTRAINT invoices_customer_fk
  FOREIGN KEY (customer_id) REFERENCES app.customers(id) NOT VALID;
COMMIT;

-- @pgevolve group id=2 transactional=false
-- @pgevolve step=3 kind=create_index_concurrent destructive=false targets=app.invoices.invoices_customer_idx
CREATE INDEX CONCURRENTLY invoices_customer_idx ON app.invoices (customer_id);

-- @pgevolve group id=3 transactional=true
BEGIN;
-- @pgevolve step=4 kind=validate_constraint destructive=false targets=app.invoices.invoices_customer_fk
ALTER TABLE app.invoices VALIDATE CONSTRAINT invoices_customer_fk;
-- @pgevolve step=5 kind=drop_column destructive=true intent_id=1 targets=app.users.legacy_email
ALTER TABLE app.users DROP COLUMN legacy_email;
COMMIT;

Step kinds — v0.2 additions (views and materialized views)

The following step kinds were added in v0.2 alongside view and materialized view support:

Step kinds — v0.2 additions (user-defined types)

The following step kinds were added in v0.2 alongside enum, domain, and composite type support:

ReplaceWithCascade. When a type change cannot be applied in place (e.g., dropping or reordering enum values, reordering composite attributes, or changing a domain's base type), the planner emits DROP TYPE <qname> CASCADE followed by CREATE TYPE. Both steps appear in the plan as drop_type (destructive — requires intent approval) and create_type.

Step kinds — v0.2 additions (functions and procedures)

The following step kinds were added in v0.2 alongside function and procedure support:

ReplaceWithCascade for functions. When a function's language or return type changes, CREATE OR REPLACE FUNCTION is not safe. The planner emits DROP FUNCTION <qname> CASCADE (destructive — requires intent approval) followed by create_or_replace_function. The CASCADE propagates to all dependent views and functions automatically.

Step kinds — v0.2 additions (extensions, triggers, partitions)

Step kinds — v0.3 additions (cluster roles)

These step kinds appear only in cluster plans (pgevolve cluster plan) — not in per-DB plans.

Step kinds — v0.3.1 additions (ownership and grants)

Step kinds — v0.3.2 additions (row-level security)

Step kinds — v0.3.3 additions (storage reloptions)

intent.toml

plan_id = "abc1234567890123"

[[intent]]
id       = 1
step     = 5
kind     = "drop_column"
target   = "app.users.legacy_email"
reason   = "drops column legacy_email"
approved = false

Every destructive step gets one [[intent]] row. intent.toml also supports [[step_override]] rows (see below). The executor:

• Reads this file at apply time.
• Refuses to run while any row has approved = false.
• Records the approval state in the audit log.

Approving destructive intents

Open intent.toml, change approved = false to approved = true for each row you want to allow, and commit the change. The plan id field must stay intact; pgevolve cross-checks it against plan.sql and manifest.toml and rejects mismatches.

Approval is intentional friction. A reviewer should be the one flipping approved = true, not the same person who authored the change. Treat the diff in intent.toml as the "are you really sure?" gate.

[[step_override]] — suppress or skip steps

intent.toml also accepts [[step_override]] rows. Step overrides let you suppress specific planner steps (e.g., skip a refresh_materialized_view during a maintenance window without regenerating the plan):

[[step_override]]
kind = "refresh_materialized_view"
target = "app.daily_summary"
suppress = true

When to use. Step overrides are appropriate for one-off operational situations (e.g., deferring an expensive REFRESH to off-peak hours). They are not a substitute for intent approval — destructive steps still require approved = true even when a [[step_override]] is present.

manifest.toml

plan_id                 = "abc1234567890123"
plan_hash               = "abc1234567890123…"  # full 64-char hex
pgevolve_version        = "0.3.3"
planner_ruleset_version = 1
source_rev              = "git:c0ffeeabc"
target_identity         = "tid-xyz"
created_at              = "2026-05-11T18:42:11Z"
target_snapshot_json    = "..."                # embedded pre-image catalog as pretty-printed JSON

Round-trip property

write_plan_dir(&p, dir); read_plan_dir(dir) == p — modulo the grafted destructive_reason (which lives in intent.toml, not in plan.sql). The round-trip is property-tested over random catalogs.

What pgevolve does and does NOT touch

pgevolve never modifies a plan directory after it's written. Edits to intent.toml's approval flags are made by users (typically in a code review). Anything else is suspicious.