23 lines
1.7 KiB
Markdown
23 lines
1.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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](../migrations.md).
|