What the agent does
The agent reads the schema and every write before it adds a column. In an API laid out like the orm/express example in prisma/prisma-examples, package.json pins prisma and @prisma/client 7.0 with @prisma/adapter-pg and pg, express 5.1 and tsx; prisma.config.ts points defineConfig at prisma/schema.prisma, keeps migrations under prisma/migrations, runs the seed with tsx prisma/seed.ts and reads the datasource URL from DATABASE_URL. The schema generates the prisma-client into prisma/generated against postgresql, with a User and a Post that has createdAt, updatedAt @updatedAt, title, content, published Boolean @default(false) and viewCount Int @default(0). src/index.ts builds the client with new PrismaClient({ adapter: new PrismaPg({ connectionString }) }) and exposes the routes.
Not every write needs a lock, and the agent says which do. PUT /post/:id/views already updates atomically with viewCount: { increment: 1 }, so two concurrent views cannot lose a count. PUT /publish/:id is the one with the race: it reads published with findUnique, then writes !postData?.published with update, so two requests that both read false both write true and the second toggle is lost. That read-then-write is the shape optimistic locking exists for, and it is the route the agent changes; DELETE and the create routes are left alone.
The change is a version Int @default(0) field on Post, a migration created with npx prisma migrate dev --name add-post-version (its SQL is one ALTER TABLE "Post" ADD COLUMN "version" INTEGER NOT NULL DEFAULT 0, so existing rows start at zero), and a rewrite of the publish route around updateMany: the where carries both the id and the version the caller read, the data sets published and version: { increment: 1 }, and a returned count of 0 means another request got there first, which the route answers with 409 and the current row so the client can retry from fresh state. The route accepts the version in the request body, and when a client does not send one it reads the row first and uses that, which still closes the window between its own read and its write. Every response that returns a post now includes version, which is what makes the first form possible.
The example has no test runner of its own, so the agent adds vitest as a dev dependency with a test script, installs PostgreSQL in its sandbox since the README's npx prisma init --db provisions a hosted database the sandbox does not have, sets DATABASE_URL, runs npx prisma migrate dev and npx prisma db seed, and writes one test: seed a post, fire two publish requests carrying the same version at once with Promise.all, and assert that exactly one returns 200, the other 409, and the row's version is 1. It runs npx tsc --noEmit against the repository's tsconfig.json (strict is on) and npm test, then opens the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add optimistic locking to this Prisma app. Read package.json, prisma.config.ts, prisma/schema.prisma, prisma/seed.ts, src/index.ts and tsconfig.json first. Identify every route that reads a row and then writes it based on what it read, and leave atomic updates such as increment alone. Add a version Int @default(0) field to each model those routes update, create the migration with npx prisma migrate dev, and rewrite each read-then-write route to use updateMany with the id and the caller's version in where and version: { increment: 1 } in data, answering 409 with the current row when count is 0; accept version from the request body and fall back to reading the row when it is absent. Include version in every response that returns the model. Add vitest with a test script, install and start PostgreSQL in the sandbox, set DATABASE_URL, run the migration and the seed, and write a test that fires two conflicting updates at once and asserts one 200, one 409 and a final version of 1. Run npx tsc --noEmit and npm test until they pass, then open a pull request that lists each route you changed, each you left alone and why.",
"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 changes prisma/schema.prisma, src/index.ts and package.json, adds a migration directory under prisma/migrations with its migration.sql, and adds the test file with a vitest configuration. Its description has two lists: the routes that now check a version, with the request shape and the 409 body, and the routes that were deliberately left alone with the reason (increment for the view counter, no read-before-write for delete), and it quotes the test output from the sandbox showing the two concurrent requests splitting into one success and one conflict.
A reviewer checks that every client of the changed route can carry version (or is happy with the read-first fallback), decides whether 409 should return the current row or just the conflict, and looks at any other model with a read-then-write pattern the agent listed as a candidate but did not change because its prompt named only the obvious one.
Existing rows get version = 0 from the column default, so the migration runs on a populated database without a backfill, and clients that ignore the new field keep working through the fallback path.
Run it on every Linear issue labelled agent
An automation on the Project with a linear trigger on linear.issue.labeled, agent in config.labels, and the prompt "this issue reports a lost update or a race on a Prisma model; add a version field and a version-checked updateMany to the routes it names, add a conflict test, and open a pull request" starts one run per labelled issue once the first model has the pattern. The trigger adds the issue after the prompt and fills in no placeholder, so the issue body is where the team says which model and which route.
A team with several Prisma services sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own schema: a service on MongoDB gets the same updateMany shape against its collection, and one that already has interactive transactions around the write gets a note that a version check is cheaper than a serialisable transaction for a single-row toggle.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A lost update is a bug that never shows in a test that runs one request at a time, and the fix is wrong in subtle ways: a version filter on update instead of updateMany throws a not-found error rather than returning a count, and an increment on the wrong side of the write loses the check. The agent runs a real PostgreSQL in its own sandbox, fires the two conflicting requests at once, and keeps the output that shows one 200 and one 409 beside the pull request.
A reviewer gets the list of routes judged and the reason for each rather than a column added to every model. A team with several services starts the same request across all of them at once.
Frequently asked questions
Why updateMany rather than update?
update takes a unique where and throws when no row matches, so a stale version surfaces as an exception the route must catch and interpret. updateMany takes any filter, including id and version together, and returns { count }, so a 0 is the conflict signal and the route stays a normal branch rather than a catch block.
Do I need a transaction as well?
Not for a single-row update: the updateMany with the version in its filter is one statement, and the database applies it atomically. A write that touches several rows together still belongs in a transaction, and the version check can sit inside it.
What happens to rows that already exist?
The migration adds the column with DEFAULT 0, so every existing row gets version 0 without a backfill, and the first version-checked update moves it to 1. The seed script needs no change.
What do clients have to do?
Read the version that comes back with the row and send it with the next update. A client that does not send one still works, because the route reads the row first and uses that version, which protects against a concurrent write between its own read and write but not against the client's own stale state.
More Prisma jobs
The same job on other stacks
- Add Optimistic Locking to a Sequelize App (Sequelize)
- Add Optimistic Locking to SQLModel Updates (SQLModel)
- Add Optimistic Locking to TypeORM Entities (TypeORM)