# Add a Drizzle Migration Drift Check to CI

Yes. An agent creates the snapshot drizzle-kit needs to diff your schema, proves generate reports no changes, and adds a CI step that fails on drift.

[Run this on Rush](https://cloud.getrush.ai/run/add-migration-check-to-ci/drizzle/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the migration folder before it reads the schema, because drizzle-kit diffs a schema against its last snapshot, not against the SQL. In a Next.js app laid out like vercel/chatbot, `drizzle.config.ts` names `./lib/db/schema.ts` and `./lib/db/migrations`, dialect `postgresql`, with `POSTGRES_URL` from `.env.local`. `package.json` has `db:generate`, `db:check`, `db:migrate` (`tsx lib/db/migrate.ts`, which the `build` script runs first) and `db:push`, with `drizzle-orm` 0.45.2 and `drizzle-kit` 0.31.10 in `pnpm-lock.yaml`. The folder holds one hand-written migration, `0000_initial.sql`, with seven `CREATE TABLE IF NOT EXISTS` statements, and `meta/_journal.json` with one entry, but no `meta/0000_snapshot.json`.

That missing file is the finding. The agent runs `pnpm db:check`, which answers that everything is fine, then `pnpm db:generate`, which, with no snapshot to diff against, writes a second migration that creates all seven tables again, `User`, `Chat`, `Message_v2`, `Vote_v2`, `Document`, `Suggestion` and `Stream`, plus `meta/0001_snapshot.json`. A check built on `generate` would fail forever; one built on `check` alone passes on any schema change. So the first step is a baseline: it compares the generated SQL with `0000_initial.sql` statement by statement (same columns, defaults, primary keys and foreign keys, in a different order), moves the snapshot to `meta/0000_snapshot.json`, deletes the generated SQL and the second journal entry, and runs `generate` again until it prints `No schema changes, nothing to migrate`.

With a snapshot in place, drift has a definition: `pnpm db:generate` writes a file when `schema.ts` differs from it, and writes nothing otherwise. The CI step goes in `.github/workflows/lint.yml`, the job that already installs with `pnpm/setup` and `require-lockfile`, after `pnpm check`: run `pnpm db:check`, then `pnpm db:generate`, then fail if `git status --porcelain lib/db/migrations` prints anything, with a message that a schema change needs `pnpm db:generate` committed. Neither command needs the database; `drizzle.config.ts` falls back to an empty URL, and `generate` reads the snapshot and the TypeScript only.

The agent proves the step both ways in its sandbox. It runs `pnpm install --frozen-lockfile` and the three commands on the baseline and reads a clean status. It then adds a column to `chat` in `schema.ts`, runs `generate`, reads the `ALTER TABLE "Chat" ADD COLUMN` migration and the new snapshot, and quotes the dirty status before reverting all of it. The description also records the one thing the baseline cannot prove: that a database migrated with `0000_initial.sql` matches the snapshot, since the hand-written file and the schema were compared by reading, not by `drizzle-kit pull`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add a Drizzle migration drift check to this app's CI. Read drizzle.config.ts, lib/db/schema.ts, lib/db/migrations and its meta folder, lib/db/migrate.ts, package.json and .github/workflows/lint.yml first. If meta has no snapshot for the existing migration, run pnpm db:generate, compare the SQL it writes with 0000_initial.sql, and turn its snapshot into the baseline for 0000 so that generate reports no schema changes; do not keep the generated SQL and do not touch 0000_initial.sql. Then add steps to lint.yml that run pnpm db:check and pnpm db:generate and fail when git status shows anything under lib/db/migrations. Prove it by adding a temporary column to chat in schema.ts, running generate, quoting the result, and reverting. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request with two files: `lib/db/migrations/meta/0000_snapshot.json`, new, and `.github/workflows/lint.yml` with three steps after `pnpm check`. `0000_initial.sql` and `_journal.json` are unchanged, `schema.ts` is as it was, and `pnpm-lock.yaml` does not move.

The description shows the statement-by-statement comparison between the generated SQL and the hand-written migration, `No schema changes, nothing to migrate` on the baseline, and the drift run: the `ALTER TABLE` file `generate` wrote for the temporary column and the `git status` lines the CI step would fail on. The run's record keeps every `drizzle-kit` invocation and its output.

Before merging, a reviewer looks at the snapshot once, since it is now the source every future diff starts from, and decides whether `db:push`, which bypasses migrations, should stay in `package.json`.

## Run it on every failed lint workflow

The CI step now refuses a schema change without a migration on every pull request. The run worth starting on Rush is the one that writes it: an automation with a `github` trigger on `workflow_run.failure` starts a run when the lint workflow fails, reads the job log for the drift message, runs `pnpm db:generate`, reads the SQL for anything a rename produced as a drop and an add, and opens a pull request with the migration and its snapshot against the failing branch.

The trigger puts the failed run after the prompt. A lint failure with no drift ends with nothing opened, as the prompt says.

## Why run it on Rush?

The hard part of this job is not the workflow step, it is finding out that `drizzle-kit check` passes on a folder with no snapshot and that `generate` would recreate the whole schema. The agent finds that by running the tools, not by reading about them, and the pull request carries the output that shows it.

Every command and every generated file stays in the run's record, so a reviewer sees the regenerated migration the agent discarded and the comparison it made before discarding it. The same request runs across a team's other Drizzle apps at once, one sandbox each, and each pull request shows whether that app had a snapshot.

## Frequently asked questions

### Why does drizzle-kit check pass with no snapshot?

`check` validates the snapshots and journal it finds for consistency; with one journal entry and no snapshot there is nothing inconsistent to report. Drift is only visible through `generate`, which needs a snapshot to diff against.

### Does the step need POSTGRES_URL in CI?

No. `generate` and `check` read `schema.ts` and the `meta` folder. The config reads `POSTGRES_URL` from `.env.local` and falls back to an empty string, which only `migrate`, `push` and `studio` would use.

### What if the hand-written SQL and the schema do not match?

Then the comparison in the first step shows the difference, and the agent stops and reports it instead of writing a baseline that hides it. A snapshot is only a baseline when it describes what the migration created.

### Will this catch someone using db:push?

Not directly. `push` changes a database without a migration file; the step checks that `schema.ts` and the migrations agree, so a schema change pushed and committed without `generate` fails CI, which is the moment to write the migration.

## More Drizzle jobs

- [Make CI Fail When a Drizzle Schema Changes Without a Migration](https://getrush.ai/run/add-migration-drift-check/drizzle/)
- [Add Query Timeouts to a Drizzle and postgres.js Setup in Next.js](https://getrush.ai/run/add-query-timeouts/drizzle/)
- [Add Read Replicas to a Drizzle App](https://getrush.ai/run/add-read-replicas/drizzle/)

## The same job on other stacks

- [Add a Migration Check to CI for a TypeORM Project](https://getrush.ai/run/add-migration-check-to-ci/typeorm/)
- [Add an Alembic Migration Drift Check to CI](https://getrush.ai/run/add-migration-check-to-ci/alembic/)

## More jobs like this: Hand off a long task

- [Make CI Fail When SQLModel Models Change Without an Alembic Migration](https://getrush.ai/run/add-migration-drift-check/alembic/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
