1.7 KiB
PostgreSQL migrations
Crank has one append-only migration authority in crank-registry. The Admin and MCP services run a read-only compatibility preflight; only the one-shot crank-migrate process may execute DDL.
For an existing installation, always run: read-only preflight, verified PostgreSQL and artifact-storage backup, plan --check, controlled apply, then a final preflight. Exit code 2 from CLI preflight means migration is required; exit code 1 blocks mutation until the reported condition is resolved.
Source command:
cargo run -p admin-api --bin crank-migrate -- plan --check
docker compose -f deploy/community/docker-compose.yml \
--env-file deploy/community/.env.example \
run --rm migrate crank-migrate preflight
The migrator reads only database configuration and retries connection for a bounded startup window. Diagnostics contain stable code, stage, nullable version, and recovery, never raw SQL, driver output, database URLs, credentials, or row data.
Published migrations are immutable and checksummed. Partial schema, unknown extension provenance, checksum drift, and future versions fail closed. Automatic down migrations, --force, destructive rollback, and arbitrary SQL input are not supported. Full N/N-1 upgrade and rollback qualification belongs to Story 7.2.
Version 3 adds nullable canonical Trace ID storage and partial Request/Trace indexes. New application writes provide both identities; historical rows remain honestly nullable and are never assigned fabricated traces.
For the complete ledger inventory, recovery table, and authoring rules, see the canonical Russian operator contract.