Neon read replicas: create for reads, never write to them

TL;DR: # Creating and using Neon read replicas ## The trap Agents create a read replica, point the app at it, and the first write fails with cannot execute ... in a read-only transaction .

Fix

1. Creating and using Neon read replicas ## The trap Agents create a read replica, point the app at it, and the first write fails with.

   Expected: this specific failure stops.

2. Create the replica from the Console, CLI, or API; it gets its own endpoint and connection string. Expected: this specific failure stops.

3. Set the replica's compute size for the workload; it does not inherit autoscaling behavior from the primary, so size it deliberately. ## Checklist - Split your connection strings:. Expected: this specific failure stops.

4. (replica) as separate env vars; never derive one from the other by hand. - In the ORM, use a read/write split or a separate client instance for the replica. - Writes failing with SQLSTATE 25006 (read-only transaction): you are pointed at the replica; check the env var. - Monitor replica lag before trusting it for freshness-sensitive reads. Expected: this specific failure stops.

Details

cannot execute ... in a read-only transaction . Or they assume replicas autoscale like the primary. Neither is true. ## The rule 1. 2. Replicas are read-only by design: route analytics, reporting, and read-heavy endpoints there; keep all writes on the primary. 3. Free plan: max 3 read replica computes per project. All plans support replicas. 4. DATABASE_URL (primary, pooled) and REPLICA_URL

When to use

You hit exactly this: Neon read replicas: create for reads, never write to them in Neon read replicas.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Neon read replicas.

Neon's read replica docs (verified live 2026-09-26): replicas are supported on all plans with a max of 3 replica computes on Free; purpose is segregating read-only work (horizontal scaling, analytics) from production operations; the connection error docs list the read-only transaction error for writes to replicas.