# 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.