fix(migrations) make resumable and safe against schema drift
From the PR description
Summary
Makes the production SQL migration process resumable and safe against schema drift in the existing Supabase database.
Why / Motivation
Production already contained parts of the document-version schema, while several historical migrations assumed older documents columns still existed. Re-running the migration sequence therefore failed on references such as d.filename, d.storage_path, and changed RPC return types.
Changes
- Added a migration ledger (public.mike_schema_migrations) so each successful migration is recorded and skipped on subsequent deploys.
- Updated the migration runner to execute only unapplied migration files and reload the PostgREST schema after completion.
- Guarded document-version backfills that depend on legacy documents metadata columns (filename, storage paths, file type, size, page count).
- Made affected migrations safe when columns or tables have already been introduced.
- Updated overview RPC migrations to drop incompatible existing function signatures before recreating them when the returned row shape changes.
- Improved migration execution so a failed deploy resumes at the failed migration rather than rerunning the entire history.
Tradeoffs & risks
- The migration ledger treats a migration as complete only after its SQL file succeeds. A failed migration must be fixed and rerun.
- Dropping and recreating overview RPC functions creates a very short availability gap for those RPC endpoints during deployment.
- Guarded legacy backfills intentionally skip data-copy work when the old source columns no longer exist; this prevents deployment failure but does not recreate removed legacy data.
- This does not replace a full schema-diff or formal migration framework; it hardens the current ordered SQL migration workflow.
How verified
- Ran migrations against the production Supabase connection through the deployment workflow.
- Confirmed previously applied migrations are recorded and skipped on rerun.
- Confirmed migration failures now identify the exact SQL file and statement, allowing fixes to resume from that point.
- Queried pg_stat_activity through psql to confirm the database connection works and no blocking migration lock was present.
Checklist
- Ran the relevant build/test command for the area changed.
- Reviewed git diff and removed unrelated changes.
- Updated docs / env examples if setup, config, or behavior changed.
- No secrets, API keys, real documents, or .env files committed.
Our analysis
Migration replay fixes - and a large, unexplained deletion of recent upstream migrations — read the full analysis →
Think the analysis missed something the PR description covers?
Commits in this PR (1)
| SHA | Subject | Author | Date | |
|---|---|---|---|---|
60ae8717 | migration fixes | Carl Ngwenya | 2026-08-14 | ↗ GitHub |
Capture this PR into my fork
Download a Markdown prompt that tells Claude how to port every
commit in this PR into your working tree. Run it via
claude -p < capture-pull-338.md from
inside the repo you want the changes in.