Catch conflicting migrations on PRs: drizzle-kit check + the new check GitHub Action

[dankochetov]

The problem: parallel migrations that merge cleanly and still break

Two branches each run drizzle-kit generate off the same migration history. Each branch gets a new migration generated from the same parent. Each PR is correct in isolation, CI is green on both, and since the migrations live in separate folders, git merges them without a single conflict. But if both migrations touch the same database object, the final database state now depends on the order they're applied in. Nothing in the git workflow surfaces this: the history forked silently.

Here's a concrete case. The schema has a status enum:

export const userStatus = pgEnum('user_status', ['active', 'inactive']);

export const users = pgTable('users', {
	id: serial().primaryKey(),
	status: userStatus().notNull().default('active'),
});

Branch A adds a banned status. drizzle-kit generate produces 0005_add-banned:

ALTER TYPE "user_status" ADD VALUE 'banned';

Branch B — opened the same day, unaware of A — removes inactive. Postgres can't drop an enum value, so the generated 0005_drop-inactive recreates the type as branch B knows it:

ALTER TABLE "users" ALTER COLUMN "status" SET DATA TYPE text;
DROP TYPE "user_status";
CREATE TYPE "user_status" AS ENUM('active');
ALTER TABLE "users" ALTER COLUMN "status" SET DATA TYPE "user_status" USING "status"::"user_status";

Both PRs merge cleanly — and now the outcome depends on apply order:

• B before A: the enum is recreated as ('active'), then banned is added → ('active', 'banned'). Works.
• A before B: banned is added first, then B's recreate replaces the enum with ('active') — the banned value silently disappears. And if any row was already set to 'banned', the USING cast fails mid-migration in whatever environment applies migrations in that order.

Same merged code, three possible databases.

The local answer: drizzle-kit check

drizzle-kit check validates your migration history and detects exactly this situation: multiple migrations generated in parallel from the same parent that modify the same database objects. It reports each conflict with the migrations and statements involved, and exits non-zero. In the upcoming release it also gains --output json, emitting a machine-readable report — which is what makes it scriptable in any pipeline.

The automated answer: the check GitHub Action

We've added a composite action that wires this into your PR flow: it runs the drizzle-kit installed in your project and posts the result as a single sticky comment that flips between states on every push:

• ✅ No conflicts — a green confirmation.
• ❌ Conflicts — a per-conflict breakdown with a diagram of the affected history, links to every migration involved, and commands to regenerate the PR's migrations on top of the base branch:

Real-world example: dankochetov/drizzle-check-action-test#7.

The step exits non-zero on conflicts, so the job can be made a required status check.

Note

This is all in a pre-release state. The action lives on the rc4 branch (referenced with @rc4), and it depends on drizzle-kit check --output json, which is not in any published npm release yet — so you can't run this in your project just yet. We'll update this thread once a drizzle-kit pre-release with --output json is on npm. In the meantime, this is exactly the stage where feedback shapes the feature — comments and propositions below are very welcome.

Using it in your pipeline

Once the drizzle-kit pre-release is out, wiring it up will look like this:

name: Drizzle check
on: pull_request

permissions:
  contents: read
  pull-requests: write

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile

      - uses: drizzle-team/drizzle-orm/actions/check@rc4

The package manager is auto-detected from the nearest lockfile (npm, pnpm, yarn, and bun are supported). For non-root configs and monorepos there are config and working-directory inputs; working-directory should point at the package that declares drizzle-kit.

One more setup step worth doing

A green check can go stale: if another PR with a conflicting migration merges first, nothing re-runs your PR's check, and the conflict would only surface after both land. To close this gap, protect the base branch with both the check as a required status check and "Require branches to be up to date before merging". GitHub then forces the PR to update with the latest base before merging, which re-runs the check against the real merge result.

We'd like your feedback

• Other providers: the core is drizzle-kit check --output json, so the GitHub Action is mostly comment-posting glue. Would you use a first-class equivalent for GitLab CI (MR notes) or Bitbucket Pipelines (reports)? Other CI systems?
• What else should the PR comment surface to make conflicts faster to resolve?
• How does this fit your monorepo setup — multiple configs/databases per repo, multiple check steps?
• Any other propositions around the conflict-checking workflow — tell us here.

[rodrigobnogueira]

Hey @dankochetov

check catches migrations that conflict with each other. I've been building the complementary piece: migrations that conflict with production uptime.

It's a linter over the artifacts drizzle-kit already generates (migration SQL + snapshots) that flags lock/rewrite hazards on Postgres. CREATE INDEX without CONCURRENTLY (including the wrapping-transaction gotcha), ADD COLUMN NOT NULL without a default, table-rewriting type changes, FK/CHECK added without NOT VALID, volatile defaults — each with the safe rewrite spelled out in the message.

Reading the snapshots (rather than just raw SQL, the way squawk does) is what kills the false positives: operations on a table created in the same migration are exempt, so bootstrap migrations lint clean. Built v1-first — the
per-migration folders, v8 snapshots and prevIds — with JSON output and a GitHub-annotations reporter for CI.

Early but working here. Would something like this be useful upstream — a kit command, a separate package, or an input to the check action? Happy to build toward whatever shape fits.

[dankochetov]

Hey, we discussed this internally and want it implemented as a part of drizzle-kit, as an opt-in advanced migrations mode. With the mode on, kit does one of two things per hazard, depending on one question: does the safe fix change the snapshot, or just the emitted SQL?

• Just the SQL -> kit rewrites it for you. Same resulting schema, so the snapshot doesn't move. CREATE INDEX → CONCURRENTLY (+ out-of-transaction), FK/CHECK → NOT VALID then VALIDATE later, SET NOT NULL → your CHECK-NOT VALID/validate/set sequence.
• The schema -> kit warns instead. The fix moves the snapshot (or needs app logic), so kit can't silently rewrite it without diverging from what you declared — it flags it at generate time and points you back. ADD COLUMN NOT NULL without a default, and the table-rewriting alter-column-type cases (new column → dual-write → backfill → swap needs your app logic).

I checked the USING INDEX path against how kit pulls: for add-unique-constraint it genuinely round-trips — Postgres adopts the concurrently-built index into the constraint, and kit's introspection reads it straight back as a unique constraint, filtering the backing index out, so the snapshot's identical and it's a clean advanced-mode rewrite. add-primary-key-on-existing-table gives the same snapshot but only skips a full table scan when the columns are already NOT NULL; on nullable ones the implied SET NOT NULL scans the whole table. So one's a rewrite, the other's a rewrite-with-a-precondition.

On your shape question: not a separate package or standalone command — both halves fold into generate under the mode. Your project is basically a working spec for the rule set. Want to help build it upstream?

[rodrigobnogueira]

Yeah, I'm in, I'd love to help build it. Honestly the linter was half an excuse to nail down the rule set, so having it live inside generate makes more sense than a standalone tool anyway.

Your rewrite-vs-warn split is a cleaner way to cut it than what I did (I just grade by lock risk). One thing worth flagging up front: the auto-rewrite side isn't only a generate change — CREATE INDEX CONCURRENTLY, and the concurrent
unique/PK index builds, can't run inside the transaction the migrator wraps each migration in. That's basically #860, and it's the piece that needs a migrator path to apply those outside a transaction. Happy to take that on.

Want me to open an issue to scope the full catalog against your split, and start with the CONCURRENTLY family since #860 is the loudest?