All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading