## TL;DR

For "cannot execute INSERT INTO ... in a read-only transaction": the usual trigger: a single DATABASE\_URL got swapped for the replica string during a config change, or the read/write split logic routes writes to the read client. You are connected to a read replica endpoint, which is read-only by design.

```text
cannot execute INSERT INTO ... in a read-only transaction
```

## Steps

1. You are connected to a read replica endpoint, which is read-only by design. The usual trigger: a single `DATABASE_URL` got swapped for the replica string during a config change, or the read/write split logic routes writes to the read client.

2. - Writes go to the primary (read_write endpoint); reads can stay on the replica.
- Keep `DATABASE_URL` and `REPLICA_URL` as separate env vars; never derive one by editing the other.
- In ORMs, check the read/write split middleware actually sends writes to the primary client.

## When to use

You are seeing this: Reads work, every write fails: cannot execute INSERT INTO... in a read-only transaction (SQLSTATE 25006). Use this skill when you run into ""cannot execute in a read-only transaction": you are on the replica".

## When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

## Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

## Why this happens

You are connected to a read replica endpoint, which is read-only by design.