Drizzle Migration Conflict

Drizzle Migration Conflict

Use this skill to help a user diagnose, repair, and prevent Drizzle Kit migration conflicts in a multi-developer repository. Drizzle migrations encode both SQL and migration snapshots, so the safe answer depends on the current migration directory shape, the Drizzle Kit version, and the git state.

When to Use This Skill

• Use when Drizzle migration files, _journal.json, or snapshot.json conflict after a pull, merge, rebase, or PR update.
• Use when drizzle-kit check reports non-commutative migrations or migration folder conflicts.
• Use when a team wants a safe repair flow for generated Drizzle migrations after schema changes converge.
• Use when designing CI or merge-queue policy to prevent repeated Drizzle migration conflicts.

Safety rules

• Start in read-only diagnosis mode unless the user explicitly asks to fix files.
• Do not run drizzle-kit migrate, drizzle-kit push, database seed scripts, or any command that connects to a live database unless the user explicitly requests it and the target is clear.
• Treat drizzle-kit check, project typechecks, and tests as command execution that may load project config, environment variables, or scripts. Inspect scripts/config first, and require an explicit non-production or disposable target before any DB-backed validation.
• Do not delete migration files, rewrite _journal.json, or run git checkout --ours, git checkout --theirs, git restore, or rm unless the user has confirmed the exact side and files to change.
• Do not recommend drizzle-kit push as the production solution for migration conflicts; it skips the auditable migration history that teams need.
• Treat --ignore-conflicts as an exception for a known false positive, not as the normal fix.
• Preserve schema source code changes unless the user explicitly asks to discard them. Conflict repair normally discards generated migrations and regenerates them from the merged schema.
• If ours and theirs could mean different branches depending on merge direction, ask the user to identify the parent branch before suggesting checkout commands.

Required references

• Read references/sources.md when the answer depends on current Drizzle behavior, official guidance, or one of the preserved external links.
• Read references/conflict-resolution.md before recommending a repair flow.
• Read references/ci-policy.md before proposing CI, merge queue, or team workflow changes.
• Read references/report-template.md before writing a diagnostic report.

Source references

The full list of official docs, Drizzle GitHub discussions, community scripts, and merge-queue references lives in references/sources.md with trust levels and caveats. Read that file whenever the answer depends on current Drizzle behavior. Re-verify the official docs and the most relevant discussion when the project's drizzle-kit major version changes, since migration internals (snapshot format, journal shape, drizzle-kit check semantics) have shifted between releases.

Mode selection

Classify the task first:

1. Diagnose - The user has a conflict or failed drizzle-kit check and wants to understand it.
2. Repair - The user explicitly asks to fix or regenerate migration files.
3. CI hardening - The user wants to prevent future conflicts in PRs or merge queues.
4. Explain - The user wants a conceptual answer or a team playbook.

When the mode is not explicit, choose Diagnose.

Each mode unlocks a specific set of actions. Do not cross these boundaries without an explicit upgrade:

• Diagnose - read-only only. Run git status, git ls-files -u, the helper script, and file inspection. Do not run drizzle-kit check, typechecks, tests, or any write command. Report findings and the proposed repair path, but do not execute it.
• Repair - adds file writes and drizzle-kit generate/check execution, each gated by the Safety rules and explicit confirmation of the exact files and side (ours/theirs) to change.
• CI hardening - adds proposing or editing CI/workflow files. Do not run migration commands against the user's database to validate the workflow; validate the workflow syntax and logic only.
• Explain - conceptual only. No commands against the repo beyond optional read-only inspection.

Repository discovery

Collect repo facts before giving commands:

git status --short
git rev-parse --show-toplevel
git rev-parse --abbrev-ref HEAD
git ls-files -u
rg --files -g 'drizzle.config.*' -g 'package.json' -g 'pnpm-lock.yaml' -g 'yarn.lock' -g 'package-lock.json'

Then inspect the relevant files:

• drizzle.config.* for out, schema, dialect, and config shape.
• package.json scripts for the project-approved generate, check, and migrate commands.
• package.json dependencies or lockfile snippets for drizzle-kit and drizzle-orm versions.
• The migration output directory, either from config or common names like drizzle/, migrations/, or src/db/migrations/.

If this skill's helper script is available, run it in read-only mode:

python3 <skill-dir>/scripts/check_drizzle_migrations.py --root .

Resolve <skill-dir> to the installed skill directory before running. Check these locations in order and use the first that contains scripts/check_drizzle_migrations.py:

1. The target repository's vendored copy: <repo-root>/skills/drizzle-migration-conflict.
2. The Claude Code skills directory: ~/.claude/skills/drizzle-migration-conflict.
3. Any other install location reported by the user's environment.

If none of these resolve, fall back to the manual git/rg inspection commands above and tell the user the helper script was not found. Use --config <file> and --migrations-dir <dir> when the project has multiple Drizzle configs or outputs. The script never connects to a database and never writes files; it only reads migration directories and reports structural issues.