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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.