> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dev migration history repair (one-time operator)

> GitHub Deploy Supabase (dev) runs supabase db push against project zkgxozahyczcnzpwhbbf. If Dev’s supabase_migrations.schema_migrations does not match the file…

GitHub **Deploy Supabase (dev)** runs `supabase db push` against project `zkgxozahyczcnzpwhbbf`. If Dev’s `supabase_migrations.schema_migrations` does not match the filenames under `supabase/migrations/`, the CLI will refuse to push (or will error if forced).

## Automated diff + repair SQL (preferred)

Use this when local migration **files** are canonical and Dev’s `schema_migrations` table is wrong (remote-only timestamps, or missing rows for files that already applied).

### 1. Export remote versions from Dev

In Dev SQL Editor (project `zkgxozahyczcnzpwhbbf`) or via Supabase MCP `execute_sql`, run:

```sql theme={null}
SELECT coalesce(json_agg(version ORDER BY version), '[]'::json)
FROM supabase_migrations.schema_migrations;
```

Save the **JSON array** (the query result) to **`reports/db/dev-schema-migrations.json`** in this repo (gitignored if your `reports/` policy ignores it; otherwise do not commit).

The array looks like `["20260305230833", ...]`. A `[{"version":"..."}]` shape from other export tools is also accepted.

### 2. Compute diff (local files vs remote)

```powershell theme={null}
npm run db:dev:diff-migrations > reports/db/dev-migration-diff.json
```

Review `onlyRemote` / `onlyLocal` counts. **Do not proceed** if the diff does not match what you expect (get a second reviewer for shared Dev).

### 3. Emit repair SQL

```powershell theme={null}
npm run db:dev:emit-repair-sql -- reports/db/dev-migration-diff.json > reports/db/dev-migration-repair.sql
```

### 4. Apply on Dev

Open `reports/db/dev-migration-repair.sql`, confirm the `INSERT` / `DELETE` blocks, then execute in the Dev SQL Editor or via MCP `execute_sql` in a single transaction (the file already wraps `BEGIN` / `COMMIT`).

Re-run **Deploy Supabase (dev)** from GitHub Actions (`workflow_dispatch` on `prod`).

**Scripts:** [`scripts/supabase/compute-migration-diff.mjs`](../../../../scripts/supabase/compute-migration-diff.mjs), [`scripts/supabase/emit-migration-repair-sql.mjs`](../../../../scripts/supabase/emit-migration-repair-sql.mjs). **NPM:** `db:dev:diff-migrations`, `db:dev:emit-repair-sql`.

***

## Symptom A — Remote versions not in repo

Log contains:

`Remote migration versions not found in local migrations directory`\
and suggests `supabase migration repair --status reverted <timestamps...>`.

**Do not blindly revert** on a shared Dev DB without confirming those rows are obsolete. Prefer the **Automated diff + repair SQL** section above, or:

1. `npx supabase link --project-ref zkgxozahyczcnzpwhbbf`
2. Compare `supabase migration list` (local vs remote) with a senior DBA / platform owner.
3. Either add missing migration files from history **or** run the exact `migration repair` plan agreed with the team.

## Symptom B — Local files “before” last remote migration

Log contains:

`Found local migration files to be inserted before the last migration on remote database`\
and suggests `supabase db push --include-all`.

Using `--include-all` in CI **re-runs** SQL that may already exist on Dev (duplicate policies / types). **Avoid** wiring `--include-all` into unattended deploy for shared Dev.

Instead: align migration history and repo using the **Automated diff + repair SQL** section or the same operator process as Symptom A.

## After repair

Re-run **Deploy Supabase (dev)** from GitHub Actions (`workflow_dispatch` on `prod`).