# Add Transactions to a Mongoose App

Yes. An agent wraps the multi-document writes in your Mongoose services in sessions with withTransaction, runs the tests on a replica set, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-transactions/mongoose/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent first finds the places where two writes must succeed or fail together. In an API laid out like hagopj13/node-express-boilerplate, `yarn.lock` resolves `mongoose` to 5.13.20 on the 3.7.4 driver, and the writes live in `src/services`. `auth.service.js` `refreshAuth` verifies a refresh token, calls `refreshTokenDoc.remove()` and then `tokenService.generateAuthTokens(user)`, which saves a new refresh document with `Token.create`; a crash between the two leaves a user with no refresh token at all. `resetPassword` saves the new password through `userService.updateUserById` and then runs `Token.deleteMany` on the reset tokens, and `verifyEmail` does the same pair in the other order. `auth.controller.js` `register` creates the user and then the tokens. And `user.service.js` `deleteUserById` calls `user.remove()` and never touches the `Token` collection, so a deleted user's refresh and reset tokens stay behind.

Mongoose 5 exposes transactions as `mongoose.startSession()` plus `session.withTransaction(fn)`, which retries on transient errors and commits when `fn` resolves. The agent threads a `session` argument through the service layer: `saveToken` passes it as `Token.create([doc], { session })`, the array form being the one that accepts options, `generateAuthTokens(user, session)` forwards it, `updateUserById` ends in `user.save({ session })`, and each `deleteMany` and `remove` gets `{ session }`. `refreshAuth`, `resetPassword`, `verifyEmail`, `register` and `deleteUserById` then each open one session, run their writes inside `withTransaction`, and call `session.endSession()` in a `finally`. `deleteUserById` gains the `Token.deleteMany({ user: userId }, { session })` it was missing. Reads that need no atomicity, such as `getUserById`, stay as they are.

Transactions need a replica set, and nothing in the repository runs one. `tests/utils/setupTestDB.js` connects to `config.mongoose.url`, which `config.js` builds from `MONGODB_URL` with a `-test` suffix; `.travis.yml` starts a plain `mongodb` service and `docker-compose.yml` runs `mongo:4.2.1-bionic` with no `--replSet`. The agent adds `mongodb-memory-server` as a dev dependency and changes `setupTestDB` to start a `MongoMemoryReplSet` with one member in `beforeAll`, connect Mongoose to its URI with the existing `useUnifiedTopology` options, and stop it in `afterAll`. Jest already runs with `-i`, so one replica set serves the whole suite. For the compose file it adds `--replSet rs0` to the `mongodb` service's command and documents the one-time `rs.initiate()` in the README.

The existing integration tests give the contract: the `POST /v1/auth/refresh-tokens` test in `tests/integration/auth.test.js` expects `Token.countDocuments()` to be 1 afterwards, and the `DELETE /v1/users/:userId` test expects the user gone. The agent keeps those passing and adds the rollback cases: a refresh where `jest.spyOn(tokenService, "saveToken")` rejects, after which the old refresh token must still exist and the count must still be 1; a user deletion after which no token for that user remains. `jest.config.js` sets `restoreMocks: true`, so the spy does not leak into the next test. `yarn lint` runs the eslint config, and `yarn test` runs the suite against the in-memory replica set.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Make the multi-document writes in this Express and Mongoose API atomic. Read package.json, yarn.lock, src/services/auth.service.js, src/services/token.service.js, src/services/user.service.js, src/controllers/auth.controller.js, src/models/token.model.js, src/models/user.model.js, src/config/config.js, tests/utils/setupTestDB.js, tests/integration/auth.test.js, tests/integration/user.test.js, jest.config.js, .travis.yml and docker-compose.yml first. Thread a session parameter through saveToken, generateAuthTokens and updateUserById, and wrap refreshAuth, resetPassword, verifyEmail, register and deleteUserById in mongoose.startSession() with session.withTransaction, ending the session in a finally. Make deleteUserById also delete that user's Token documents inside the same transaction. Transactions need a replica set: add mongodb-memory-server as a dev dependency and change setupTestDB to start a MongoMemoryReplSet in beforeAll and stop it in afterAll; add --replSet rs0 to the mongodb service in docker-compose.yml and document rs.initiate() in the README. Add tests that force the second write to fail and assert the first was rolled back. Run yarn lint and yarn test and open a pull request that quotes the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

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 changes `src/services/auth.service.js`, `token.service.js` and `user.service.js` (the sessions and the forwarded `session` option), `src/controllers/auth.controller.js` (register inside one transaction), `tests/utils/setupTestDB.js` (the in-memory replica set), `tests/integration/auth.test.js` and `user.test.js` (the rollback cases), `package.json` and `yarn.lock` (the dev dependency), `docker-compose.yml` (the `--replSet` command) and the README (the one-time `rs.initiate()`). Its description quotes the Jest output and lists each function that now runs in a transaction.

A reviewer checks that every write inside a `withTransaction` callback carries the session, since a write without it runs outside the transaction and commits on its own, and that the callback does not swallow errors, because `withTransaction` only aborts when the callback rejects. They also decide whether `register` should stay transactional, given that the unique index on `email` already rejects a duplicate before any token is written.

The orphaned-token fix in `deleteUserById` is called out separately in the description, since it changes behaviour and not only atomicity.

## Run it on every Linear issue labelled data-integrity

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `data-integrity` starts one read-only run per issue; its runs read the repository and comment, so the automation posts a plan of which service functions pair two writes and which need a session. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to find the functions from the issue text.

The pull request itself comes from the team's own server: a handler sends this body with `POST /o/{org}/sessions`, the repository in `resources`, the issue URL as a second resource, and a `request_id` that is a UUID v5 of the Linear issue id, so a redelivered webhook returns the run already started.

## Why run it on Rush?

A transaction change is only believable with a failure test, and a failure test is only believable on a real replica set. The agent downloads the MongoDB binary, starts the replica set, runs the suite under it in its own sandbox and keeps the output with the pull request, so the reviewer sees the rollback assertion pass rather than reading the session plumbing and hoping.

The sessions are threaded through the functions this repository has, with the orphaned tokens it actually leaves behind. A team with several Mongoose services starts the same request on each at once and reads one pull request per service, each listing the write pairs found there.

## Frequently asked questions

### Does this work on a single MongoDB server?

No. MongoDB runs transactions only on a replica set or sharded cluster, which is why the tests start a one-member `MongoMemoryReplSet` and the compose file gains `--replSet rs0`. A single-member replica set on one machine is enough for development.

### Why pass the session everywhere instead of using a global?

Mongoose attaches a session per operation. A query or `create` call that does not receive `{ session }` runs outside the transaction and is not rolled back, so each write in the callback must name it explicitly.

### Why does Token.create use an array?

In Mongoose 5, `Model.create(doc, options)` treats a second plain object as another document. Only `Model.create([doc], { session })` reads the options, so `saveToken` switches to the array form and returns the first element.

### Will the existing tests still need a running MongoDB?

No. `setupTestDB` starts the in-memory replica set itself, so `yarn test` no longer depends on `MONGODB_URL` pointing at a server. The first run downloads the MongoDB binary once.

### What about the pre-save password hook?

`user.save({ session })` still runs the `pre('save')` hook in `user.model.js`, so a password reset inside the transaction is hashed exactly as before.

## More Mongoose jobs

- [Add Two-Factor Authentication to an Express and Mongoose API](https://getrush.ai/run/add-two-factor-auth/mongoose/)
- [Fix "Model.find() no longer accepts a callback" After a Mongoose Upgrade](https://getrush.ai/run/fix-mongoose-callback-error/mongoose/)
- [Fix "DeprecationWarning: Mongoose: the `strictQuery` option will be switched back to `false` by default in Mongoose 7"](https://getrush.ai/run/fix-mongoose-strictquery-deprecation-warning/mongoose/)

## The same job on other stacks

- [Add Transactions to a Prisma App](https://getrush.ai/run/add-transactions/prisma/)
- [Add Transactions to a Sequelize App](https://getrush.ai/run/add-transactions/sequelize/)
- [Wrap Multi-Step Writes in TypeORM Transactions](https://getrush.ai/run/add-transactions/typeorm/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
