What the agent does
The agent reads how migrations are produced before adding a check for them. In an app laid out like nextjs/saas-starter, drizzle.config.ts points schema at ./lib/db/schema.ts, out at ./lib/db/migrations, sets dialect: 'postgresql' and reads dbCredentials.url from POSTGRES_URL. package.json has db:generate as drizzle-kit generate, db:migrate as drizzle-kit migrate, db:setup and db:seed through tsx, pins drizzle-orm ^0.43.1 and drizzle-kit ^0.31.1, and ships a pnpm-lock.yaml at lockfileVersion: '9.0', so the package manager is pnpm 9 or later and there is no packageManager field to pin it. lib/db/migrations/ holds one migration, 0000_soft_the_anarchist.sql, with meta/0000_snapshot.json and meta/_journal.json beside it. There is no .github directory, so this is the first workflow, and the README's setup runs pnpm db:setup, pnpm db:migrate and pnpm db:seed against a local Postgres.
The check rests on how drizzle-kit generate works: it reads the schema file and the latest snapshot under out, and writes a new SQL file, a new snapshot and a journal entry only when they differ. It needs the dialect and the schema path and no database, which the agent confirms in its sandbox by running pnpm db:generate with POSTGRES_URL unset; the non-null assertion on process.env.POSTGRES_URL in the config is a TypeScript annotation, not a runtime check. So in CI, a schema change that was committed without running generate shows up as new untracked files under lib/db/migrations/ after the command runs, and a clean tree means every change has its migration.
The workflow is .github/workflows/migrations.yml, on pull_request and on push to main, with pnpm/action-setup and actions/setup-node on Node 22, which matches the @types/node ^22 the project pins, then pnpm install --frozen-lockfile. Three steps follow. pnpm db:generate --name ci_drift_check runs the generator; a git status --porcelain lib/db/migrations step fails the job when it prints anything and, before failing, prints the generated SQL with cat, so the author reads the migration they forgot to commit in the job log rather than guessing. Then pnpm drizzle-kit check, added to package.json as db:check, runs Drizzle's consistency check over the migrations folder, which catches two branches that each generated a migration from the same snapshot and were merged. The agent adds packageManager: "pnpm@9…" to package.json with the version its sandbox resolved, which is what pnpm/action-setup reads, and documents the job in the README beside the db: scripts.
To prove the job fails for the right reason, the agent runs the three steps in its sandbox twice: once on the clean tree, where generate reports no schema changes and the status step prints nothing, and once after adding a nullable column to users in lib/db/schema.ts without committing a migration, where generate writes 0001_ci_drift_check.sql with the ALTER TABLE and the status step lists it and fails. It pastes both runs, reverts the column, and confirms pnpm build is unaffected since the job touches no application code.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a CI check that fails when the Drizzle schema changes without a migration in this Next.js app. Read package.json, pnpm-lock.yaml's header, drizzle.config.ts, lib/db/schema.ts, lib/db/drizzle.ts, lib/db/migrations/ including meta/_journal.json, lib/db/setup.ts and the README first. Confirm in your sandbox that pnpm db:generate runs with POSTGRES_URL unset. Write .github/workflows/migrations.yml on pull_request and push to main with pnpm/action-setup, Node 22 and pnpm install --frozen-lockfile, then: run pnpm db:generate --name ci_drift_check; fail if git status --porcelain lib/db/migrations prints anything, printing the generated SQL first so the author sees it; run pnpm drizzle-kit check, added to package.json as db:check. Add a packageManager field pinning the pnpm version your sandbox resolved. Document the job in the README beside the db scripts. Run the steps twice in your sandbox, once on the clean tree and once after adding a nullable column to users in lib/db/schema.ts without a migration, paste both runs into the pull request, and revert the column. Change no schema, migration or application code.",
"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
The pull request adds .github/workflows/migrations.yml and changes package.json for the db:check script and the packageManager field, and the README. Its description pastes the two sandbox runs: the clean run where generate reports no changes and check passes, and the deliberate drift run where the job prints the ALTER TABLE "users" ADD COLUMN … it generated and fails on the status step, so the reviewer sees the message an author will get.
Nothing changes for the application: no schema, migration or runtime file is touched, and the job needs no database secret, which the description states since the config reads POSTGRES_URL. The one new requirement on contributors is that a schema change arrives with its pnpm db:generate output committed, which is what the README now says.
Before merging, a reviewer decides whether the job should also run pnpm db:migrate against a Postgres service container to prove the migrations apply, which the pull request describes as the next step, and whether push to main is wanted or pull_request alone.
Run it on every repository without a migration check
An engineer who was bitten by a column that existed in the schema file and not in production starts this from the terminal with this body and moves on. One POST /o/{org}/sessions per Drizzle repository, each with its own resources URL; GET /o/{org}/github lists every repository the Rush GitHub App reaches, so a short script can start a run only where drizzle.config.ts exists and .github/workflows/ has no migration job.
Send a request_id, a UUID v5 of the repository's full name, with each body so a retried call returns the run it already started. A key runs at most max_concurrent sessions at once, 4 by default, and a request past that answers 202 with status: "queued" and starts when a slot frees. A webhook_url on the key brings run.completed for each run the key started, with data.session_url to read for the pull request link.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A drift check is only worth having if it fails when it should and passes when it should, and the way to know is to run it both ways. The agent does that in its own sandbox, with the real drizzle-kit the lockfile pins, including the deliberate schema edit that a reviewer would otherwise have to stage by hand, and the pull request carries both outputs rather than a claim.
The transcript keeps every command and its output, so the reviewer reads the generated SQL and the failing step without checking the branch out. A team with several Drizzle repositories adds the check to all of them at once, each run in its own sandbox, and nothing merges until a person reads the diff.
Frequently asked questions
Does the job need a database?
No. drizzle-kit generate compares the schema file with the latest snapshot in the migrations folder, and drizzle-kit check reads the folder; neither connects. The agent confirms this by running pnpm db:generate with POSTGRES_URL unset, and the workflow sets no secret. Applying the migrations to a Postgres service container is a separate job the pull request describes.
What does drizzle-kit check add over generate?
generate answers whether the schema has changes no migration covers. check answers whether the migrations folder itself is consistent, for example when two branches each generated a migration from the same snapshot and both were merged, leaving two files that claim the same parent. It is the case generate cannot see from the schema alone.
Why print the generated SQL before failing?
So the author learns from the job log what migration is missing and can run pnpm db:generate locally knowing what to expect. A bare red check sends them to the docs; the ALTER TABLE in the log tells them which column they forgot.
Why add a packageManager field?
pnpm/action-setup reads the pnpm version from package.json's packageManager field when no version input is given. The lockfile's lockfileVersion: '9.0' says pnpm 9 or later, but a field pins the exact version so CI and laptops install from the lockfile the same way.
Will this fail on a schema change I made on purpose?
Only until you commit the migration it produces. The job runs the same pnpm db:generate you run locally; once the SQL, the snapshot and the journal entry are in the branch, the tree is clean after the step and the job passes.
More Drizzle jobs
The same job on other stacks
More jobs like this: Hand off a long task
- Add Migrations to a Sequelize Express App (Sequelize)