Merge pull request #10 from zvx-echo6/docs/migration-policy

docs: migration idempotency and runner policy

docs/migrations.md

@@ -0,0 +1,27 @@
+# Migration policy
+
+## 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.