Rebase Drizzle Migration

Guide the user through recovering from a messy drizzle migration state after rebasing onto upstream/main.

Agent Workflow

1. Diagnose - Analyze the current state and identify what's wrong
2. Explain - Tell the user what happened and why
3. Fix - Run the necessary commands to fix the migration state
4. Verify - Check results after each step

Diagnosis Phase

When this skill is invoked, first diagnose the problem:

# Check for duplicate journal entries
cat packages/db/drizzle/meta/_journal.json | tail -30

# List migration files
ls packages/db/drizzle/*.sql

# Check diff against upstream
git diff upstream/main --stat -- packages/db/

# Check what upstream has
git show upstream/main:packages/db/drizzle/meta/_journal.json | tail -20

# Find the merge base
git merge-base HEAD upstream/main

Look for:

• Duplicate idx values in journal
• Same migration tag appearing twice
• Migration files that exist on branch but not upstream (or vice versa)
• Schema files that don't match upstream's expected state

The Problem (Explain to User)

Drizzle migrations are sequential and tracked in packages/db/drizzle/meta/_journal.json. The issue occurs when:

1. You branched off main at migration 0008
2. You added your own migration 0009 (or overwrote 0008)
3. Meanwhile, upstream added their own 0009
4. You rebased onto upstream

This results in:

• Conflicting or duplicate migration files
• A corrupted journal with duplicate entries or wrong indices
• Snapshot files that don't match the journal
• drizzle-kit generate asking nonsensical questions about column renames

Fix Process

---

Step 1: Checkout upstream/main

Switch to upstream/main to get a clean database state:

git checkout upstream/main

---

Step 2: Apply migrations to database

Run the migration command:

bun --bun --cwd packages/db drizzle-kit migrate

---

Step 3: Switch back to feature branch

Switch back to the feature branch:

git checkout <branch-name>

---

Step 4: Clean up migration artifacts

Run cleanup commands:

# Identify what needs cleanup by checking diff
git diff upstream/main --stat -- packages/db/drizzle/

# Check current journal state
cat packages/db/drizzle/meta/_journal.json | tail -20

Then perform cleanup:

• Remove migration SQL files the branch added: rm packages/db/drizzle/0010_*.sql
• Remove corresponding snapshots: rm packages/db/drizzle/meta/0010_snapshot.json
• Restore journal from upstream: git checkout upstream/main -- packages/db/drizzle/meta/_journal.json
• Restore any accidentally modified snapshots: git checkout upstream/main -- packages/db/drizzle/meta/0009_snapshot.json
• Restore schema files that should match upstream (files user didn't intentionally modify)

---

Step 5: Verify clean state

Run verification:

git diff upstream/main --stat -- packages/db/

The diff should now show ONLY schema file changes (e.g., sessions.ts), not migration files.

---

Step 6: reseet database state

Ask the user (DO NOT DO THIS YOURSELF UNLESS YOU ARE ASKED TO DO SO) to reset the database state to the upstream/main state.

# reset the database volumes
docker compose down -v && docker compose up -d

# then seed the existing migrations
bun --bun --cwd packages/db drizzle-kit migrate

This will delete all data in the local database and re-apply the upstream migrations.

---

Step 7: Regenerate migration

Generate a fresh migration for the schema changes:

bun run db:migrations:generate

This should create a new migration file (e.g., 0010_something.sql) with just the changes.

---

Step 8: Apply migration locally

Apply the new migration to the local database:

bun --bun --cwd packages/db drizzle-kit migrate

---

Step 9: Verify and commit

After migration succeeds, verify:

# Check the final diff
git diff upstream/main --stat -- packages/db/

# Run typecheck
bun run typecheck

# Run tests
bun --bun run test

The diff should show:

• The new migration SQL file
• The new snapshot JSON
• Updated journal
• Schema file changes

Troubleshooting

If drizzle-kit asks about column renames during generate

The schema doesn't match what drizzle expects. Check if:

• Schema files were accidentally reverted during rebase
• Upstream renamed columns that your schema still has with old names

Fix: git checkout upstream/main -- packages/db/src/tables/<file>.ts for files you didn't intend to modify.

If journal still has duplicates after cleanup

The checkout didn't work or there are staged changes. Run:

git checkout upstream/main -- packages/db/drizzle/meta/_journal.json

If local DB is in weird state

Run migrate on upstream/main again, then switch back to branch.

Key Files Reference

• packages/db/drizzle/*.sql - Migration SQL files (sequential: 0000, 0001, ...)
• packages/db/drizzle/meta/_journal.json - Tracks all migrations and their order
• packages/db/drizzle/meta/NNNN_snapshot.json - Schema snapshot after each migration
• packages/db/src/tables/*.ts - Drizzle schema definitions

Commands Reference (for agent)

# All commands are non-interactive and safe for agent to run:
git diff upstream/main --stat -- packages/db/
git show upstream/main:packages/db/drizzle/meta/_journal.json
cat packages/db/drizzle/meta/_journal.json
ls packages/db/drizzle/*.sql
git checkout upstream/main -- <file>  # restore specific file
rm packages/db/drizzle/0010_*.sql     # cleanup
bun run db:migrations:generate
bun --bun --cwd packages/db drizzle-kit migrate