Incident brief
Read-only SQL transaction
A write was attempted inside a transaction explicitly marked READ ONLY. PostgreSQL blocked the write instead of allowing it.
In 10 seconds
- What
- Read-only SQL transaction
- What triggers it
- BEGIN READ ONLY.
- The fix
- Don't open the transaction as READ ONLY if it needs to write to ordinary tables.
- Proof
- Reproduced on PostgreSQL 16.14 → An INSERT into an ordinary table inside a READ ONLY transaction was rejected with SQLSTATE 25006. No row was added.
The fix
What to do right now
The immediate, application-level response to this error.
- Don't open the transaction as READ ONLY if it needs to write to ordinary tables.
- Writes to temporary tables are allowed even inside a READ ONLY transaction — see the premium test.
- Don't assume SET SESSION CHARACTERISTICS can flip the current transaction to read/write mid-flight — see the counterexample.
BEGIN;
INSERT INTO audit.events VALUES (1);
COMMIT;Diagnose
See it live on the server
Run these against the affected instance to confirm the diagnosis before you act.
Standard triage — not specific to this error
These are canonical PostgreSQL system-catalog queries, shown as SQL to run. No sample output is attached because this is general triage, not a captured lab transcript.This SQLSTATE does not have an error-specific live snapshot yet. These are the canonical system-catalog queries you run against the affected server to see the problem in real time — standard triage, not a reproduced transcript.
What is running right now
Active backends, how long each has been running, and what it is waiting on.
SELECT pid,
state,
wait_event_type,
wait_event,
now() - query_start AS running_for,
left(query, 80) AS query
FROM pg_stat_activity
WHERE state <> 'idle'
AND pid <> pg_backend_pid()
ORDER BY running_for DESC NULLS LAST;Who is blocking whom
Turn raw blocking PIDs into the actual queries on both sides of the wait.
SELECT blocked.pid AS blocked_pid,
blocked.query AS blocked_query,
blocking.pid AS blocking_pid,
blocking.query AS blocking_query
FROM pg_stat_activity AS blocked
JOIN LATERAL unnest(pg_blocking_pids(blocked.pid)) AS b(pid) ON true
JOIN pg_stat_activity AS blocking ON blocking.pid = b.pid
WHERE cardinality(pg_blocking_pids(blocked.pid)) > 0;Locks that are still waiting
Every lock a backend has requested but not yet been granted.
SELECT l.pid,
l.locktype,
l.mode,
l.granted,
COALESCE(c.relname, l.transactionid::text) AS object
FROM pg_locks l
LEFT JOIN pg_class c ON c.oid = l.relation
WHERE NOT l.granted
ORDER BY l.pid;Why it happens
What PostgreSQL is telling you
The mechanism behind the error, grounded in the official manual — not paraphrased.
PostgreSQL 16 Documentation — SET TRANSACTION
When a transaction is read-only, the following SQL commands are disallowed: INSERT, UPDATE, DELETE, MERGE, and COPY FROM if the table they would write to is not a temporary table; all CREATE, ALTER, and DROP commands...Read the full section on postgresql.org →
The blocked INSERT
READ ONLY marks the whole transaction as non-writing. Per the manual, INSERT into a non-temporary table is one of the commands explicitly disallowed in that mode, so PostgreSQL blocked it immediately.Confirming no row was added
audit.events is still empty — the blocked INSERT never took effect.Reproduce & verify
A real, single-session PostgreSQL reproduction
A literal transcript of SQL run against a live PostgreSQL instance in an isolated lab — the commands below are exactly what was executed.
- 1BEGIN READ ONLY.
- 2Try to INSERT into an ordinary (non-temporary) table.
- 3SQLSTATE 25006 is reported; the transaction is aborted.
One client: open a READ ONLY transaction, then try to INSERT into an ordinary table.
DROP TABLE IF EXISTS audit.events;
CREATE TABLE audit.events (id int);BEGIN READ ONLY;
INSERT INTO audit.events VALUES (1);
ROLLBACK;SELECT count(*) FROM audit.events;What PostgreSQL actually returned
NOTICE: table "events" does not exist, skipping
DROP TABLE
CREATE TABLEBEGIN
ERROR: cannot execute INSERT in a read-only transaction
ROLLBACK count
-------
0
(1 row)The manual's disallowed-commands list explicitly excludes temporary tables from the write restriction. This was tested directly: a temp table created before the READ ONLY transaction, written to inside it.
Create a temp table outside any transaction, then INSERT into it from inside a READ ONLY transaction.
Without this
Above: INSERT into an ordinary table inside READ ONLY is rejected.
With this, tested
Below: INSERT into a pre-existing temp table inside the same READ ONLY mode succeeds.
What Pro unlocks here
- The exact prevention SQL — copy-paste ready
- Raw psql output captured from the Docker lab
- A senior-DBA action list to take it further
- Live monitoring queries to catch it in production
- The deeper audit: fix-that-fails counterexample, GUC before/after, server-log evidence
Related & next steps
Follow the thread
Everything this error touches — jump straight to the sibling error, term, runbook, or parameter.
Verification
- Last verified
- 2026-07-16 (Docker lab, PostgreSQL 16.14)
- Reviewed by
- Verified against PostgreSQL 16.14 in an isolated lab environment
- Audit status
- reviewed