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

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. Or they assume replicas autoscale like the primary. Neither is true.

The rule

1. Create the replica from the Console, CLI, or API; it gets its own endpoint and connection string.
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. 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: DATABASE_URL (primary, pooled) and REPLICA_URL (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.

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.