fix(migrations) make resumable and safe against schema drift

🟢 open · #338 · open-legal-products/mike ← smtp/mike-2 · opened 24d ago by smtp · +133-1,531 across 14 files · ↗ on GitHub

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.

⬇ Download capture-pull-338.md