What the agent does
The agent reads the migration history before it adds a check, because the history is where drift hides. In an app like trpc/examples-next-prisma-starter, prisma/schema.prisma has a postgres datasource read from DATABASE_URL, the prisma-client-js generator and one model, Post, with id, title, text, createdAt with @default(now()) and updatedAt with @updatedAt; a comment above createdAt says it is unique so it can serve as a pagination cursor. prisma/migrations/ holds four folders: 20211019164222_init creates the table and unique indexes on createdAt and updatedAt, 20220307124425_non_unique_timestamps drops both, 20220918091608_pagination adds the createdAt unique index back, and 20220918134120_revert drops it again, with migration_lock.toml set to postgresql. So the schema file and the applied migrations agree today, the comment does not, and nothing in the repository would catch the next time someone edits the schema and forgets prisma migrate dev.
package.json already has the pieces: prisma ^6.7.0, migrate-dev running prisma migrate dev, migrate running prisma migrate deploy, and prebuild running generate then migrate. .github/workflows/main.yml has two jobs, e2e and unit, each with a postgres service on port 5432 and POSTGRES_HOST_AUTH_METHOD: trust, pnpm/action-setup, Node 22 and pnpm prebuild before the tests. The agent adds a third job, migrations, that reuses the same service block, installs with pnpm install, and runs two commands against it: pnpm prisma migrate diff --from-migrations prisma/migrations --to-schema-datamodel prisma/schema.prisma --shadow-database-url "$SHADOW_DATABASE_URL" --exit-code, which replays every folder into an empty shadow database and compares the result with the schema file, and pnpm prisma migrate deploy followed by pnpm prisma migrate diff --from-url "$DATABASE_URL" --to-schema-datamodel prisma/schema.prisma --exit-code, which catches a migration folder whose SQL was hand-edited after it was generated. With --exit-code, migrate diff returns 0 for no difference and 2 when there is one, so the step fails only on drift.
The two URLs point at two databases on the one service, created with psql in a step before the diffs, because --from-migrations needs a database it may wipe. The job runs on push and pull_request like the others and adds paths filters for prisma/** so a change to a React component does not run it; the agent explains in the workflow comments why a schema-only trigger would miss a deleted migration folder and keeps the folder in the filter. It also adds a migrate:check script to package.json with the shadow-database form so a developer can run the same check before pushing, with the connection strings read from .env the way .env already carries DATABASE_URL.
To prove the check, the agent runs it in its sandbox against a PostgreSQL it installs with apt and starts there: first on the repository as it is, where the diff is empty and the step passes, then after adding @unique to createdAt in schema.prisma to match the stale comment, where migrate diff prints the CREATE UNIQUE INDEX it would need and exits 2. It reverts that edit, leaves the comment as a one-line fix noting the index was dropped in 20220918134120_revert, and includes both outputs in the pull request. It runs pnpm prebuild and pnpm tsc as well, so nothing else moved.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a Prisma migration drift check to this repository's CI. Read package.json, .env, prisma/schema.prisma, every migration.sql under prisma/migrations/ and migration_lock.toml, and .github/workflows/main.yml first. Add a migrations job to main.yml with the same postgres service the other jobs use, a step that creates a second database for a shadow URL, then prisma migrate diff --from-migrations prisma/migrations --to-schema-datamodel prisma/schema.prisma with that shadow URL and --exit-code, and prisma migrate deploy followed by prisma migrate diff --from-url DATABASE_URL --to-schema-datamodel prisma/schema.prisma --exit-code. Filter the job to changes under prisma/ and say in a comment why the whole folder is watched. Add a migrate:check script to package.json for the shadow-database form. Install and start PostgreSQL in the sandbox, run the check as the repository stands, then add @unique to createdAt in schema.prisma, run it again to show the non-zero exit and the index it reports, and revert that edit. Fix the comment above createdAt so it matches the migrations. Run pnpm prebuild and pnpm tsc, and open a pull request that includes both diff outputs.",
"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 that changes .github/workflows/main.yml, package.json and the one comment in prisma/schema.prisma. No migration folder is added, renamed or edited, and the Prisma client, routers and tests are untouched.
The description shows the new job's steps, the empty diff from the clean run and the CREATE UNIQUE INDEX diff with exit code 2 from the deliberately drifted run, so a reviewer sees the check both pass and fail before it ever runs in Actions. The full command log is in the transcript at GET /o/{org}/sessions/{id}/messages.
Before merging, a reviewer decides whether the job should also run on a schedule to catch a database changed by hand, whether the paths filter should go so the check runs on every pull request, and whether migrate:check belongs in a pre-push hook.
Run it on every pull request that touches prisma/
Once the job is in main.yml, GitHub runs it on every pull request. To have an agent fix the drift it finds rather than only report it, add an automation on the Project with a github trigger on pull_request.synchronize and the prompt "if the migrations job failed on this pull request, run prisma migrate dev with a name taken from the schema change, commit the new migration folder to this branch, and explain the SQL in a comment"; the trigger puts the pull request after the prompt, and the run checks out that branch.
For the repositories you have now, send one POST /o/{org}/sessions per repository with this body and a request_id that is a UUID v5 of the repository's full name, so a retry returns the run already started. The key's webhook_url reports when each run the key starts finishes.
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 trustworthy once you have watched it fail, and that takes a disposable Postgres, a second database for the shadow replay, and the patience to break the schema on purpose and put it back. The agent does that loop on its own machine, with both outputs kept, so the pull request shows the exit code 2 the team is buying rather than asserting it.
Every command stays with the run, and several repositories can get the same job at once, each in its own sandbox with its own pull request and its own proof.
Frequently asked questions
Why two diffs instead of one?
--from-migrations replays the SQL files into an empty shadow database and compares the result to schema.prisma, catching a schema edit with no migration. --from-url after migrate deploy compares the database the migrations produce when applied in order, catching a migration file edited after it was generated. Each misses what the other finds.
Does it need a separate shadow database?
Yes. --from-migrations requires --shadow-database-url and may drop everything in that database, so the job creates a second database on the same postgres service with psql rather than pointing it at DATABASE_URL.
Will this fail on the existing history with its revert?
No. Replaying init, non_unique_timestamps, pagination and revert in order yields a Post table with no unique index on createdAt, which is what schema.prisma declares, so the diff is empty. Only the comment claimed otherwise, and the pull request fixes that line.
Why filter the job to prisma/ changes?
To keep a frontend-only pull request from waiting on a Postgres service. The filter covers the whole prisma/ folder, not just schema.prisma, so deleting or editing a migration folder also triggers it; remove the filter if you prefer the job on every pull request.
More Prisma jobs
The same job on other stacks
More jobs like this: Hand off a long task
- Add Migrations to a Sequelize Express App (Sequelize)