# Add Read Replicas to a TypeORM App

Yes. An agent adds TypeORM's replication option to your NestJS app from one environment variable, keeps writes and read-after-write on the primary, and opens a PR.

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

## What the agent does

The agent reads where the connection is configured, because in this codebase it is configured twice. In an API built from brocoders/nestjs-boilerplate, `src/database/data-source.ts` builds the `AppDataSource` the TypeORM CLI uses from `DATABASE_TYPE`, `DATABASE_URL`, `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`, `DATABASE_PASSWORD` and `DATABASE_NAME`, with a pool `max` from `DATABASE_MAX_CONNECTIONS` and SSL from `DATABASE_SSL_ENABLED`; `src/database/typeorm-config.service.ts` builds the same options for `TypeOrmModule.forRootAsync` from `ConfigService`, which `src/database/config/database.config.ts` fills after `class-validator` checks each variable, `DATABASE_URL` or the host fields but not neither. `typeorm` is 0.3.28 and `pg` 8.20.0 in `package.json`. Repositories such as `src/users/infrastructure/persistence/relational/repositories/user.repository.ts` read through an injected `Repository<UserEntity>`: `find` with `skip` and `take` for lists, `findOne` by id, and `save` after `create`.

TypeORM reads from replicas when the options carry a `replication` object with a `master` and a list of `slaves`: ordinary `find`, `findOne` and query-builder selects go to a replica, and every write, every transaction and every query runner asked for `master` goes to the primary. The agent adds one function, `buildReplication`, in `src/database/config/`, that reads a new `DATABASE_REPLICA_URLS` variable, comma-separated, and returns the `replication` object with the existing primary settings as `master` and one entry per replica URL, or nothing when the variable is unset. Both the data source and the config service call it, so the two files stay in step through one source instead of a third copy, and the `EnvironmentVariablesValidator` gains the variable as optional. `env-example-relational` gets the key with an empty value so the CI path is unchanged.

The part that needs reading is read-after-write. A replica lags, so a `save` followed by a `find` of the same row in one request can miss. The agent searches the relational repositories and the services that call them for that shape, the `create` methods that `save` and then map the saved entity are safe because they use the returned row, but any method that writes and then queries by id in the same call is listed in the pull request and switched to the primary with `createQueryRunner('master')`, each with the file and line. It changes nothing else about how queries are written.

Proof runs twice. In its sandbox the agent runs the relational e2e suite through the repository's Compose file with `DATABASE_REPLICA_URLS` unset, so the options have no `replication` key and the suite behaves as before, then again with the variable pointing at the same Postgres service, so every read goes through the replica path with no lag to hide behind. It adds a unit test for `buildReplication` covering unset, one URL and two URLs, and runs `npm run lint`, `npm run test` and the Compose e2e command, quoting each.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add read replicas to this TypeORM app. Read src/database/data-source.ts, src/database/typeorm-config.service.ts, src/database/config/database.config.ts, src/database/config/database-config.type.ts, env-example-relational, docker-compose.relational.ci.yaml and the relational repositories under src/*/infrastructure/persistence/relational/ first. Add a DATABASE_REPLICA_URLS variable, comma-separated and optional, validated with the others. Write one function that returns TypeORM's replication option with the existing primary settings as master and one slave per URL, or nothing when unset, and call it from both the data source and the config service; do not copy the options a third time. Search every relational repository and service for a save followed by a read of the same row in one method, list each, and route those reads to the primary with a master query runner. Add a unit test for the function. Run npm run lint, npm run test and the relational Compose e2e command twice, with the variable unset and with it pointing at the Compose Postgres, and quote the results. Open a pull request.",
  "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

What comes back is a pull request that adds one function and its test under `src/database/config/`, changes `data-source.ts` and `typeorm-config.service.ts` to call it, adds the variable to the validator, the config type and `env-example-relational`, and edits the few repository methods that read after a write, each named in the description with its line. The description quotes `npm run lint`, the unit tests, and the two e2e runs.

The run's record keeps both Compose runs side by side, so a reviewer can see the suite pass with and without the replica path and read the TypeORM query log, which is on outside production, for the second run.

Before merging, a reviewer provides a real replica URL for staging and decides whether reports and list endpoints should tolerate lag, which they do by default, and whether any endpoint the agent did not flag must read the primary for product reasons.

## Run it on every service that reads more than it writes

A team moving several services onto a replica starts one run per repository from a script on its own server: `GET /o/{org}/github` lists every repository the installation reaches, the script keeps the ones whose `package.json` depends on `typeorm`, and calls `POST /o/{org}/sessions` with this body and that repository in `resources`, with a `request_id` that is a UUID v5 of the repository's full name, so running the script twice returns the runs already started.

Each run reads its own repository. One that configures the connection in one place gets a smaller change than this one; one that already uses a `url` only gets the master built from it; one with raw `query` calls gets each one listed as a read or a write. The pull requests arrive one per repository, each with its own e2e runs in the record, and the script reads each session's `pr_url` as the runs finish.

## Why run it on Rush?

Replication is a one-key option with a long tail: two config files that must agree, a validator that must accept the new variable, and a codebase to audit for reads that cannot lag. Done by hand, the audit is the part that gets skipped. In a Rush sandbox the agent reads every relational repository, lists each read-after-write with its line, and proves the change with the repository's own Compose e2e suite in both modes.

The pull request shows the audit, the two runs and the one function both config files now share, so the reviewer checks a list rather than re-reading the services. Across every TypeORM service a team runs, the job runs in parallel, one sandbox and one pull request each.

## Frequently asked questions

### Do transactions and writes ever hit a replica?

No. TypeORM sends every `save`, `insert`, `update`, `delete` and every transaction to `master`, and a query runner created with `'master'` reads there too. Only plain selects outside a transaction use a replica.

### What happens when DATABASE_REPLICA_URLS is unset?

The function returns nothing, the options have no `replication` key, and the connection is exactly what the repository builds today. That is how the first e2e run in the pull request proves nothing changed for environments without a replica.

### Why point the replica at the primary in the test?

Because the Compose file has one Postgres, and the point of the second run is to drive every read through the replica path and the master query runners, not to measure lag. A real replica with lag is what the staging check is for.

### How were the read-after-write spots found?

By reading each relational repository and the services that call them for a `save` followed by a read of the same row in one method. The pull request lists every one with its file and line, and a reviewer who knows a flow the search cannot see adds to the list.

## More TypeORM jobs

- [Add Seed Data to a NestJS TypeORM App](https://getrush.ai/run/add-seed-data/typeorm/)
- [Add Slow Query Logging to a TypeORM + NestJS App](https://getrush.ai/run/add-slow-query-logging/typeorm/)
- [Add Soft Delete to TypeORM Entities](https://getrush.ai/run/add-soft-delete/typeorm/)

## The same job on other stacks

- [Add Read Replicas to a Drizzle App](https://getrush.ai/run/add-read-replicas/drizzle/)
- [Add Read Replicas to a Prisma App](https://getrush.ai/run/add-read-replicas/prisma/)

## More jobs like this: Hand off a long task

- [Add Reading Time to an Eleventy Blog](https://getrush.ai/run/add-reading-time/eleventy/)

## 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/)
