matt/central
1
0
Fork 0
mirror of https://github.com/zvx-echo6/central.git synced 2026-05-21 18:14:44 +02:00
Code Issues Projects Releases Packages Wiki Activity
central/docs/migrations.md
Matt Johnson 98e9d95810 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

1.1 KiB
Raw Blame History

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.