drizzle-migration-conflict-resolution

name	drizzle-migration-conflict-resolution
description	Resolve Drizzle migration merge/rebase conflicts in OneQuery by rewinding local-only migration history and regenerating migration metadata. Use when conflicts involve packages/db/src/migrations/meta/_journal.json, migration SQL files in packages/db/src/migrations/*.sql, or migration snapshots in packages/db/src/migrations/meta/*_snapshot.json.

DB Migration Conflict Resolution

Goal

Resolve Drizzle migration conflicts without manually editing migration SQL or meta/_journal.json.

Workflow

1. Inspect conflict scope.

• Run git status --short.
• Confirm the migration conflict includes packages/db/src/migrations/meta/_journal.json.
• If non-migration conflicts need product decisions, stop and ask the user.

2. Fetch the base branch.

• Run git fetch origin.
• Default to origin/main unless the user requests another base branch.

3. Keep incoming journal history as baseline.

• Run git checkout --theirs packages/db/src/migrations/meta/_journal.json.
• Do not hand-edit packages/db/src/migrations/meta/_journal.json.

4. Find local-only migration artifacts.

• Run:

comm -23 <(git ls-tree -r --name-only HEAD packages/db/src/migrations | sort) \
  <(git ls-tree -r --name-only origin/main packages/db/src/migrations | sort)

• Treat returned SQL and snapshot files as local-only migration history.

5. Remove local-only migration artifacts.

• Run git rm <each-local-only-file> for returned migration SQL and snapshot files.
• Keep incoming branch migration files intact.

6. Regenerate migration chain from schema.

• Run cd packages/db && bun run db:generate.
• Let Drizzle regenerate the next migration and update meta/_journal.json.

7. Stage and verify.

• Run git add packages/db/src/migrations packages/db/src/migrations/meta/_journal.json.
• Confirm no conflict markers remain:

rg -n "^(<<<<<<<|=======|>>>>>>>)" packages/db/src/migrations/meta/_journal.json

• Inspect generated SQL and verify it reflects expected schema deltas only.

8. Finalize merge/rebase.

• Continue merge/rebase flow with git commit or git rebase --continue.
• If pre-commit/pre-push hooks rewrite migration metadata formatting, commit the formatted files so the branch is clean.

Guardrails

• Never manually create or edit files inside packages/db/src/migrations/.
• Never manually edit packages/db/src/migrations/meta/_journal.json.
• Regenerate via bun run db:generate after history rewind.
• If generated migration includes unexpected schema changes, stop and ask the user before committing.