central/docs/migrations.md

# Migration policy

## Migrations are the sole source of truth

The `sql/migrations/` directory contains all schema definitions. There is
no separate schema.sql file; use `pg_dump -s central` to generate a
human-readable snapshot of the current schema when needed.

## Migrations must be idempotent

New migration files (007+) must use guards so they can be safely
re-run without error:

- `CREATE TABLE IF NOT EXISTS ...`
- `CREATE INDEX IF NOT EXISTS ...`
- `INSERT ... ON CONFLICT DO NOTHING` (or `ON CONFLICT ... DO UPDATE`
  where the intent is upsert)
- `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...`

Migrations 003-006 predate this policy and are grandfathered. Do not
rewrite them.

## All schema changes go through migrate.py

Direct `psql` execution bypasses the `schema_migrations` tracker and
was the cause of the v0.2.0 reconcile. If a migration needs to be
applied on the live system, run:

    sudo -u central /opt/central/.venv/bin/python -m scripts.migrate

Never apply migration SQL directly via `psql`, even as a superuser,
even "just to test." If migrate.py has a bug that's blocking you, fix
migrate.py.
docs: migration idempotency and runner policy 2026-05-17 04:08:20 +00:00			`# Migration policy`

fix(tests): replace stub tests with real DB migration tests - Replace pytest.skip stubs with actual DB tests against central_test - Test backfill for all three adapters (nws, firms, usgs_quake) - Test FK RESTRICT, NOT NULL, and FK validation constraints - Test schema changes (source dropped, adapter exists with constraints) - Delete stale sql/schema.sql (migrations are sole source of truth) - Update docs/migrations.md with schema.sql removal note Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> 2026-05-17 17:39:38 +00:00			`## Migrations are the sole source of truth`

			The `sql/migrations/` directory contains all schema definitions. There is
			no separate schema.sql file; use `pg_dump -s central` to generate a
			`human-readable snapshot of the current schema when needed.`

docs: migration idempotency and runner policy 2026-05-17 04:08:20 +00:00			`## Migrations must be idempotent`

			`New migration files (007+) must use guards so they can be safely`
			`re-run without error:`

			- `CREATE TABLE IF NOT EXISTS ...`
			- `CREATE INDEX IF NOT EXISTS ...`
			- `INSERT ... ON CONFLICT DO NOTHING` (or `ON CONFLICT ... DO UPDATE`
			`where the intent is upsert)`
			- `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...`

			`Migrations 003-006 predate this policy and are grandfathered. Do not`
			`rewrite them.`

			`## All schema changes go through migrate.py`

			Direct `psql` execution bypasses the `schema_migrations` tracker and
			`was the cause of the v0.2.0 reconcile. If a migration needs to be`
			`applied on the live system, run:`

			`sudo -u central /opt/central/.venv/bin/python -m scripts.migrate`

			Never apply migration SQL directly via `psql`, even as a superuser,
			`even "just to test." If migrate.py has a bug that's blocking you, fix`
			`migrate.py.`