All jobs

Review Prisma Migrations in Every Pull Request

An agent applies a pull request's Prisma migrations to a fresh Postgres with data, checks them against the schema, and comments on SQL that locks or loses data.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent checks out the pull request's branch in its own sandbox and reads the migration setup before the migration. In a project laid out like trpc/examples-next-prisma-starter, prisma/schema.prisma has a postgres datasource on DATABASE_URL and one Post model with a UUID id, title, text, createdAt defaulting to now() and updatedAt with @updatedAt; prisma/migrations/migration_lock.toml pins the provider to postgresql; package.json depends on prisma and @prisma/client 6.7 and wires prebuild to prisma generate followed by prisma migrate deploy, migrate-dev to prisma migrate dev, db-reset to prisma migrate dev reset and db-seed to tsx prisma/seed.ts, which upserts one post under a fixed id. .github/workflows/main.yml starts a postgres service with POSTGRES_HOST_AUTH_METHOD: trust, runs pnpm prebuild and then the Playwright and Vitest suites, so CI already applies every migration to an empty database and never to one with rows in it.

Then it reads the history, because this repository's own migrations show what the review is for. 20211019164222_init created Post with unique indexes on both createdAt and updatedAt; 20220307124425_non_unique_timestamps dropped both; 20220918091608_pagination added the unique index on createdAt back with Prisma's generated warning that it fails if duplicate values exist; and 20220918134120_revert dropped it again. Two posts created in the same millisecond would have made the third migration fail in production after passing on the empty CI database. The agent lists the pull request's new directories under prisma/migrations/, confirms no already-applied migration.sql was edited, and reads each statement for what it does to a table with data: a NOT NULL column added without a default, a type change that rewrites the table, a unique index over columns that may repeat, a DROP with no replacement.

It then proves what it read. It starts the Postgres version the workflow uses in the sandbox, runs prisma migrate deploy from the base branch, loads synthetic rows shaped to the schema and to the risks it spotted, including posts with equal createdAt values, and applies the pull request's migrations with prisma migrate deploy while a second session holds an open transaction on the table, so a statement that waits for an exclusive lock is seen waiting. It runs prisma migrate status to confirm the database and the directory agree, and prisma migrate diff --from-migrations prisma/migrations --to-schema-datamodel prisma/schema.prisma with a shadow database and --exit-code to confirm the migrations produce exactly the schema the model declares, since a hand-edited migration.sql can drift from schema.prisma and migrate deploy does not check.

Prisma migrations have no down step, so the last thing the agent writes for each risky statement is the way back: the SQL that would restore the dropped column from a backup, or the two-migration version of a NOT NULL change that adds the column nullable, backfills, then adds the constraint. It also checks the application code the pull request changes against the migration: a field added to the model and used in src/server/routers/post.ts through defaultPostSelect before the column exists is a deploy-order problem, not a schema one, and the comment says so.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Review the Prisma migrations added by the open pull request in resources. Read prisma/schema.prisma, prisma/migrations/migration_lock.toml, every existing migration.sql, prisma/seed.ts, package.json, .env and .github/workflows/main.yml first. List the new migration directories and confirm no previously applied migration.sql was edited. Start Postgres in your sandbox with a fresh database and synthetic data only, never a production dump: apply the base branch's migrations with prisma migrate deploy, insert rows shaped to the schema including values that would collide with any new unique index, then apply the pull request's migrations with prisma migrate deploy while another session holds an open transaction on each affected table, and record which statements wait. Run prisma migrate status, and prisma migrate diff from the migrations directory to the schema with a shadow database and --exit-code, and report any drift. Comment on the pull request at the exact lines of each migration.sql: the SQL, what happened when it was applied with data and a concurrent transaction, the safe alternative, and the way back since Prisma has no down migrations. Check that model fields the code uses exist after the migration. Change no file and push nothing.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app/pull/42"
    }
  ]
}
  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

The pull request receives review comments on the specific lines of each new migration.sql: the CREATE UNIQUE INDEX that failed on the two rows with equal createdAt, the ALTER TABLE that waited behind the open transaction, the dropped column and the SQL that would restore it, each with the output of the sandbox apply beside it. A migration with nothing wrong gets one comment saying it applied cleanly with data and under a concurrent transaction, with the migrate status and migrate diff results.

The summary comment states whether the migrations match schema.prisma, whether any applied migration was edited, and whether the application code depends on a column before the migration that creates it. Nothing is pushed: the agent changes no file in the pull request.

Before merging, a reviewer reads each comment against the deploy order they use, decides whether a two-step migration is worth it for the table sizes they have, and whether the backfill belongs in the migration or in a script run beforehand.

Run it on every pull request that touches prisma/migrations

In the console, add an automation to the Project with this prompt and a GitHub trigger on pull_request.opened and pull_request.synchronize. The trigger adds the event after the prompt, and only work by an owner, member or collaborator fires it; pull requests from forks never do. Each push starts a run on the pull request's branch, and a pull request that adds nothing under prisma/migrations/ ends with a short note and no comments.

A team that wants the review in its own tooling sends this body from its server when its GitHub webhook handler sees a pull request touching prisma/migrations/, with the pull request URL in resources and a request_id that is a UUID v5 of the pull request's head SHA, so a redelivered webhook returns the run already started.

The use case this job follows, with its automation and trigger: Review every pull request.

Why run it on Rush?

Migration review by eye finds the dropped column and misses the lock and the duplicate. This repository's own history, a unique index on a timestamp added and reverted a month apart, is what an empty CI database lets through. Applying the migration to a Postgres with rows in it while another session holds a transaction is what shows whether the statement waits or fails, and that needs a database the reviewer does not want on their laptop.

The agent runs the apply, the status check and the diff in its own sandbox and keeps their output, so each comment quotes what Postgres did rather than what the reviewer suspects. Several pull requests are reviewed at once, each in its own database, and none of them touches a real one.

Frequently asked questions

Does applying the migration to a fresh database prove it is safe in production?

No, and the comments do not claim it. The sandbox shows the kind of failure, a duplicate value or a waiting lock, on synthetic rows. How long the lock waits on the real table depends on its size and traffic, which the comment names as the thing the team knows and the agent does not.

What does the `migrate diff` step catch?

A migration.sql that was edited by hand after prisma migrate dev generated it, so the migrations no longer produce the schema the model declares. prisma migrate deploy applies the files as they are and does not detect that drift, which is why the agent compares the migrations directory against schema.prisma through a shadow database and reports a non-zero exit code.

Prisma has no down migrations. What does the review say about rollback?

For each destructive statement it writes the way back as SQL: how to restore a dropped column from a backup, or how to drop a new constraint, and for a NOT NULL change it proposes the add-nullable, backfill, then constrain sequence as two migrations. The reviewer decides which of those to keep as a runbook.

Will it comment on migrations that are fine?

Once, briefly: that the migration applied with data and under a concurrent transaction, with migrate status clean and migrate diff empty. A pull request that adds no migration gets a one-line note and no inline comments.

Does it run `prisma migrate dev`?

No. migrate dev is a development command that can reset the database and generate new migrations, and the review must apply exactly the files in the pull request. The agent uses migrate deploy, migrate status and migrate diff only.

More Prisma jobs

The same job on other stacks

Keep reading