Read your own writes, off the primary

2026-08-31T23:36:00+00:00
Your API accepts the change. It returns 201 Created or 200 OK, the system has saved the user's change, and the moment the user clicks, the change disappears from the app, only to resurface seconds later. That's if you are lucky. There's no error. The change simply ceased to exist for a while.
In the era of server-side-rendered applications this was a non-issue: either the state was managed as part of a single request, or the user was too slow to outrun the system. The modern application changed that. It fires off the mutation, invalidates the cache, and wakes up the state management, all in parallel and milliseconds after the write. The snappier your frontend feels, the more reliably it outruns your replica.
Throw a collaborative product into the mix and it gets worse, because every change sent over a websocket invalidates state on every teammate's open tab and device, and all of them go back to the same endpoints on the same replicas.
Some of the common workarounds are:
pin reads to the primary (which you really want to avoid)</li>
add sleep delays</li>
set flags in Redis</li> </ul>
Your application has to act like a traffic conductor. It guesses the replication lag using timeouts and Redis flags. The replica already knows exactly where it stands; your code just has no way to ask.
PostgreSQL 19 adds a way to ask. On the standby:
WAIT </span>FOR</span> LSN </span>'0/554D1B78'</span>;</span></span></code></pre>
The standby blocks until it has replayed that position, then returns and lets the next statement run. That is all a reader needs to know to follow the numbers below.</p>
There is a great deal more to it, and my friend Gülçin Yıldırım Jelínek wrote it up last week</a>: why it has to be a top-level command rather than a function, the self-deadlock that rule prevents, and the 2016 proposal it grew out of. Read hers for that; it is the account I kept failing to write, and it saved me a lot of work. Everything below is what happened when I put the statement in front of traffic and measured it.</p>
What makes a replica lag</a>
</h2>
Replica lag is a combination of factors, and each of them is separately visible. Three of them show up in one query.</p>
SELECT</span> application_name, write_lag, flush_lag, replay_lag,</span></span>
       pg_current_wal_lsn()</span> -</span> replay_lsn </span>AS</span> bytes_behind</span></span>
FROM</span> pg_stat_replication;</span></span></code></pre>
write_lag</code> and flush_lag</code> are the mechanics of the network and the disk on the standby. The WAL segments travelling over the network and hitting storage. In the same availability zone, interactions take just a fraction of a millisecond. However, in cross-region networks, this time continues to increase. This is your floor.</p>
replay_lag</code> is the problem. Shipping WAL is usually simple; applying it is the part that makes your change visible to queries. Recovery is a single startup process replaying records one at a time, and while prefetch can warm the I/O ahead of it, nothing applies two records at once. It competes with everything else the machine is doing, and your change might be queued behind something far more expensive: a bulk import, index maintenance, anything that produces WAL faster than one process can replay it. That is how lag jumps from milliseconds to seconds.</p>
The fourth factor is the shape of the read traffic on the replica, which is ironically the thing you were trying to achieve. Roughly, and this one is illustrative rather than from the companion repo:</p>
read load on the replica</th> replay_lag</th></tr></thead>

none</td> 5 ms</td></tr>
8 clients (pgbench -S)</td> 25 ms</td></tr>
48 clients</td> 1134 ms</td></tr>
</tbody></table>

Replica waits up to max_standby_streaming_delay</code>, 30 seconds by default, before killing the query blocking the replay.
</div>
Read backends compete with the startup process for CPU and I/O, and recovery can clash with a long-running query outright, blocking the replay of any record that would invalidate that query's snapshot. All it takes is one analytical query to pause replay for half a minute. The more successfully you offload reads to the replica, the more lag you introduce there.</p>
The routing strategies. Measured.</a>
</h2>
Now back to those common workarounds, measured against WAIT FOR</code>. The workload is straightforward: insert a row on the primary, then read it back like a web request would. Do this 1,000 times with 8 concurrent workers, against a local streaming replica with no added lag.</p>

All tests were run on postgres:19beta3</code>, two containers on one host (Apple Silicon), a primary and one asynchronous streaming replica. Every number comes from the companion repo</a>. Both nodes are on loopback, so the latencies are a floor: a real cross-AZ replica adds its round trip to every figure. The shape</em> of the results is easy to reproduce; the exact timings are not.
</div>
routing</th> stale reads</th> reads served by replica</th> p50</th> p95</th> p99</th></tr></thead>

read the primary (sticky)</td> 0 / 1000</td> 0</td> 1.9 ms</td> 3.1 ms</td> 4.3 ms</td></tr>
read the replica, immediately</td> 992 / 1000</strong></td> 1000</td> 1.8 ms</td> 2.5 ms</td> 9.2 ms</td></tr>
sleep 50 ms, then read replica</td> 0 / 1000</td> 1000</td> 53.9 ms</td> 57.5 ms</td> 62.0 ms</td></tr>
WAIT FOR</code>, then read replica</td> 0 / 1000</td> 1000</td> 2.8 ms</td> 4.2 ms</td> 6.4 ms</td></tr>
</tbody></table>
Those are numbers I had to re-run several times, because the second line looks implausible until you sit with it. The replica is on the same machine as its primary and talks to it over loopback, and naive reads still miss 99.2% of the time.</p>
The last row is the case for WAIT FOR</code>. Every read served correctly, one to two milliseconds slower than going to the primary at every percentile, which is two extra round trips: one to the primary to learn the commit LSN, one for the wait itself on the replica.</p>
You shall not synchronously commit</a>
</h2>
There's one seemingly simple fix that avoids all of this. Make the primary wait for the standby and you never have to look back. It nearly works, which is the problem.</p>
Adding the standby to synchronous_standby_names</code> took staleness from 593 out of 600 reads down to somewhere between 3 and 17</strong>, depending on the run. That is a fix that passes every test you'll write and then fails in production, because synchronous_commit = on</code> waits for the standby to flush</em> the WAL, not to replay</em> it, and your read lands between those two instants.</p>
The setting that actually closes the gap is remote_apply</code>, which makes every commit on the primary wait for replay on the standby: the batch job, the migration, and every writer that is never going to read from a replica. WAIT FOR</code> moves that cost to the one reader that needs it, bounded, at the moment it needs the data.</p>
The timeout is a routing budget</a>
</h2>
WAIT FOR LSN 'lsn'</span></span>
    [ WITH ( option [, ...] ) ]</span></span>
</span>
where option can be:</span></span>
</span>
    MODE 'mode'</span></span>
    TIMEOUT 'timeout'</span></span>
    NO_THROW</span></span></code></pre>
MODE</code> says what the standby has to have done with the WAL. standby_replay</code> is the default and the only one that helps here: it waits until the record has been replayed and is visible to queries. The others stop earlier, at flushed to disk (standby_flush</code>) or merely written (standby_write</code>), or wait on the primary instead (primary_flush</code>).</p>
TIMEOUT</code> is where a read guarantee stops being a database feature and turns into a system architecture choice.</p>
The option does not control correctness. A timeout means "the replica is too far behind for me to wait", and the right response is to read from the primary instead. The runs below hold the replica 50 ms behind with recovery_min_apply_delay</code>, so there is always something to wait for.</p>
TIMEOUT</code></th> stale reads</th> served by replica</th> fell back to primary</th> p50</th></tr></thead>

500ms</code></td> 0 / 400</td> 400</td> 0</td> 53.4 ms</td></tr>
20ms</code></td> 0 / 400</td> 0</td> 400</td> 24.0 ms</td></tr>
5ms</code></td> 0 / 400</td> 0</td> 400</td> 7.3 ms</td></tr>
</tbody></table>
Correctness never moves. What moves is where the reads go and what they cost. Within the budget, lag turns into latency on the replica</em> and the primary never sees it; reads only get handed back when lag exceeds what the architecture is willing to accept.</p>
That fallback is where the good news stops. The reason you moved reads off the primary in the first place was to take load off it, and a cluster-wide lag event times out every waiter at roughly the same moment. The system then does the opposite of what you built it for and stampedes the primary with the traffic it was supposed to be shielded from. The burst is bigger than your normal concurrency, too, because a budget that takes a read from 3 ms to 500 ms leaves a hundred times more requests in flight at the same arrival rate. In many designs it is better to fail the request than to hand it back. That decision is the reason TIMEOUT</code> is an architecture question and not a tuning knob.</p>
The second issue is that a waiting reader holds a connection</strong> for the whole duration of the timeout. At a few thousand reads per second with a generous budget, you run out of connections exactly when you can least afford to. Budget the timeout against your connection pool size.</p>
The last point, mentioned in Gülçin's post</a>, is promotion. WAIT FOR</code> only means something on a node that is replaying WAL, so a newly promoted primary answers not in recovery</code>.</p>
Implementing it</a>
</h2>
You may not need any of this. If your reads genuinely tolerate staleness, that is a legitimate architecture and not a gap in it. You will know when you hit the problem.</p>
Every application or framework that can route reads to a replica already ships a sticky-window version of this: pin to the primary for N seconds, sleep, or keep a flag. WAIT FOR</code> replaces the guess with a fact and leaves the rest of the routing alone. Four steps:</p>

After the commit</strong>, on the primary, retrieve the LSN with SELECT pg_current_wal_flush_lsn()</code>.</li>
Store the LSN</strong> wherever the session lives. It's a string like 0/3F8A120</code> identifying a WAL position and it isn't a secret, although anyone who can read it can work out how fast your primary writes.</li>
Before the read</strong>, on the replica, run WAIT FOR LSN '<lsn>' WITH (MODE 'standby_replay', TIMEOUT '…', NO_THROW)</code>. Top-level statement, meaning not inside a function or a DO block; an ordinary READ COMMITTED transaction block is fine. NO_THROW</code> turns errors into a status row you can branch on.</li>
Use it.</strong> success</code> means you can go ahead with the read on that standby. timeout</code> or not in recovery</code> means read the primary instead, fail the request, or serve the replica's answer with the staleness flagged so a client that applied the write optimistically can keep it.</li>
</ol>
Expose the failure rate of step 4 as a metric. It is the number that tells you whether your budget is set anywhere near reality, and it is the signal a circuit breaker should trip on when it isn't.</p>
There is technically a fourth outcome: the wait can die.</strong> NO_THROW</code> converts statuses into a row, not the connection into an immortal one. A waiting session on a standby is still subject to recovery conflicts, and some of those take out every backend regardless of what it was doing</a>. Replaying a tablespace drop is the documentation's own example.</p>
Which LSN to record</a>
</h3>
Step 1 said after the commit</em>. The tempting shortcut is to take the LSN while you are already in the transaction and save yourself a round trip.</p>
BEGIN</span>;</span></span>
INSERT INTO</span> messages(author, body) </span>VALUES</span> (</span>'Radim'</span>, </span>'Hello Postgres!'</span>);</span></span>
</span>
-- this is a lie!</span></span>
SELECT</span> pg_current_wal_insert_lsn();</span></span>
COMMIT</span>;</span></span></code></pre>
That position comes from inside</em> the transaction, before the commit record has been written. In a single idle session the gap is small: 0/554D1B50</code> inside, 0/554D1B78</code> after. Forty bytes. pg_walinspect</code> will tell you what is in them:</p>
postgres=# SELECT start_lsn, end_lsn, record_length, resource_manager, record_type</span></span>
             FROM pg_get_wal_records_info('0/554D1B50','0/554D1B78');</span></span>
-[ RECORD 1 ]----+-------------</span></span>
start_lsn        | 0/554D1B50</span></span>
end_lsn          | 0/554D1B78</span></span>
record_length    | 34</span></span>
resource_manager | Transaction</span></span>
record_type      | COMMIT</span></span></code></pre>
That is one record: Transaction/COMMIT</code>, 34 bytes padded out to the 40-byte gap. Now watch the replica replay that stretch. It applies the INSERT record and the row lands on the page, invisible, because nothing has yet told the standby that the transaction committed. The next record does that, and it is the one your LSN stopped short of. Waiting on the in-transaction position waits for the row to exist. Waiting on the post-commit position waits for it to count.</p>
The token doesn't stop at the session</a>
</h2>
The LSN is a short string, so it travels: a response header, a field on a job payload, a value you hand to another service. Distributed systems carry this kind of consistency token anyway, and here it happens to be a WAL position.</p>
That has two consequences. If you can receive tokens from more than one source, keep the larger one, because it is the only one that also guarantees the smaller. And don't compare them as strings. Cast to ::pg_lsn</code> and let Postgres do the ordering.</p>
This is not a general fix for stale replicas. WAIT FOR</code> covers the writes whose LSNs you are holding and nothing else. A concurrent write, committed a moment before your read, still shows up whenever the replica gets to it, exactly as before.</p>
Sample implementation</a>
</h2>
The whole pattern is about thirty lines: two pools, a validated token, and a branch. Nothing below is specific to Go beyond the syntax; it is the four steps above with one function each.</p>
CaptureLSN</code> is step 1, and the only thing that matters about it is which pool it runs on: the primary, after the commit. Replayed</code> is steps 3 and 4 together, collapsing every possible answer into one boolean, because from the application's side there are only two outcomes: this standby has your write, or you read from the primary. PoolFor</code> is the routing decision, and it is three lines because that is all it is.</p>
Step 2 is deliberately omitted. Only you can decide where the token lives between the request that wrote and the request that reads: a session, a signed cookie, a response header the client echoes back, a field on a job payload. The code assumes only that something hands it an LSN.</p>
// WAIT FOR takes no bind parameters, so both operands are interpolated and</span></span>
// both are validated first. The LSN has usually been to a cookie and back</span></span>
// before it gets here; the budget is often config, which is not the same as</span></span>
// trusted.</span></span>
var</span> (</span></span>
	lsnRE</span>    =</span> regexp.</span>MustCompile</span>(</span>`^[0-9A-Fa-f]{1,8}/[0-9A-Fa-f]{1,8}$`</span>)</span></span>
	budgetRE</span> =</span> regexp.</span>MustCompile</span>(</span>`^[0-9]{1,6}(ms|s)$`</span>)</span></span>
)</span></span>
</span>
// CaptureLSN runs on the PRIMARY, after the commit. Before it, or on any other</span></span>
// connection, and you get a position that says nothing about your write.</span></span>
func</span> CaptureLSN</span>(</span>ctx</span> context</span>.</span>Context</span>,</span> primary</span> *</span>pgxpool</span>.</span>Pool</span>) (</span>string</span>,</span> error</span>) {</span></span>
	var</span> lsn</span> string</span></span>
	// flush, not insert: at synchronous_commit=on this is already at or past</span></span>
	// your commit record, without covering WAL other backends merely inserted.</span></span>
	err</span> :=</span> primary.</span>QueryRow</span>(ctx,</span> "SELECT pg_current_wal_flush_lsn()::text"</span>).</span>Scan</span>(</span>&</span>lsn)</span></span>
	return</span> lsn, err</span></span>
}</span></span>
</span>
// Replayed asks one replica whether it has caught up to lsn, within budget.</span></span>
// Any answer other than success (timeout, promotion, a dead replica) means</span></span>
// "read the primary", so every failure path returns false rather than an error.</span></span>
func</span> Replayed</span>(</span>ctx</span> context</span>.</span>Context</span>,</span> replica</span> *</span>pgxpool</span>.</span>Pool</span>,</span> lsn</span>,</span> budget</span> string</span>)</span> bool</span> {</span></span>
	if !</span>lsnRE.</span>MatchString</span>(lsn)</span> || !</span>budgetRE.</span>MatchString</span>(budget) {</span></span>
		return</span> false</span></span>
	}</span></span>
	conn, err</span> :=</span> replica.</span>Acquire</span>(ctx)</span></span>
	if</span> err</span> !=</span> nil</span> {</span></span>
		return</span> false</span></span>
	}</span></span>
	defer</span> conn.</span>Release</span>()</span></span>
</span>
	// One statement, one round trip. Simple protocol: the interpolated LSN makes</span></span>
	// every call a distinct SQL string, which would thrash a statement cache.</span></span>
	var</span> status</span> string</span></span>
	q</span> :=</span> fmt.</span>Sprintf</span>(</span>"WAIT FOR LSN '</span>%s</span>' WITH (MODE 'standby_replay', TIMEOUT '</span>%s</span>', NO_THROW)"</span>, lsn, budget)</span></span>
	if</span> err</span> :=</span> conn.</span>QueryRow</span>(ctx, q).</span>Scan</span>(</span>&</span>status); err</span> !=</span> nil</span> {</span></span>
		return</span> false</span></span>
	}</span></span>
	return</span> status</span> ==</span> "success"</span></span>
}</span></span>
</span>
// PoolFor is the whole routing decision: the replica has to earn the read.</span></span>
// replica must address ONE standby. A replay position belongs to a node, so a</span></span>
// pool pointed at a load-balanced read endpoint (a VIP, round-robin DNS, a</span></span>
// multi-host connection string) can run the wait on one standby and the read</span></span>
// on another, and the fallback never fires.</span></span>
func</span> PoolFor</span>(</span>ctx</span> context</span>.</span>Context</span>,</span> primary</span>,</span> replica</span> *</span>pgxpool</span>.</span>Pool</span>,</span> lsn</span>,</span> budget</span> string</span>)</span> *</span>pgxpool</span>.</span>Pool</span> {</span></span>
	if</span> lsn</span> ==</span> ""</span> ||</span> Replayed</span>(ctx, replica, lsn, budget) {</span></span>
		return</span> replica</span></span>
	}</span></span>
	return</span> primary</span></span>
}</span></span></code></pre>
Note what Replayed</code> does not do: hold the connection. It releases it back to the pool before the read happens, because the replay position belongs to the standby, not to your backend. Any connection to the same node will do.</p>

The Go above is the tested file with its imports trimmed. Verified against the same pair: a caught-up replica serves the read and the write is visible; a replica held two seconds behind falls back to the primary, which sees the write; an empty token reads the replica; and a malformed token ("0/1; drop table messages"</code>, a trailing newline, "0/"</code>), a malformed budget, or an unreachable replica routes to the primary rather than raising.
</div>
Rails calls it a write</a>
</h3>
Similar investigation in Rails uncovered interesting finding. Active Record decides whether a statement is a write by matching its leading keyword against an allowlist: select</code>, with</code>, show</code>, explain</code> and a dozen more. WAIT FOR</code> is not on that list, so it is a write by exclusion, and the reading role always prevents writes. prevent_writes: false</code> is ignored there, and dropping replica: true</code> from the pool config doesn't help either, because a pool marked replica</code> reports preventing_writes?</code> in every role.</p>
The way through is to go under the statement layer, on the connection the read will use:</p>
ActiveRecord</span>::</span>Base</span>.</span>connected_to</span>(</span>role: :reading</span>)</span> do</span></span>
  ActiveRecord</span>::</span>Base</span>.</span>with_connection</span> do</span> |c|</span></span>
    c.</span>raw_connection</span></span>
     .</span>exec</span>(</span>"WAIT FOR LSN '#{lsn}' WITH (TIMEOUT '#{</span>BUDGET</span>}', NO_THROW)"</span>)</span></span>
     .</span>values</span>.</span>dig</span>(</span>0</span>,</span> 0</span>)</span> ==</span> "success"</span></span>
  end</span></span>
end</span></span></code></pre>
Real writes are still blocked, and the wait lands on the same backend as the read. The cost is that Active Record never sees the statement. This is the same bug class as DECLARE CURSOR</code> (rails/rails#37960) and COPY TO</code> (#47870), both fixed by adding the keyword to the allowlist. Until WAIT FOR</code> joins them, this is the workaround.</p>
Notes regardless of stack</a>
</h3>
WAIT FOR</code> needs no framework support at all. It is one statement and a conditional branch.</p>

a transaction block is fine, so wrapped test suites are not a problem. BEGIN; WAIT FOR …; SELECT …; COMMIT;</code> returns success</code> and the read sees the row, because at READ COMMITTED no snapshot is held while the wait runs and the SELECT</code> takes its own afterwards. What WAIT FOR</code> refuses is a function or a DO block, and any isolation level above READ COMMITTED.</li>
your driver will work. WAIT FOR</code> goes over the extended query protocol every driver speaks. A prepared-statement cache is the one thing to watch, because the LSN is a literal rather than a parameter, so a naive cache accumulates one entry per distinct write.</li>
PgBouncer in transaction mode needs no special handling. The wait goes through as its own implicit transaction, and a read issued afterwards in a separate transaction still sees the write, because the replay position belongs to the node rather than to your session. Verified against PgBouncer 1.25.2. Two cautions that do apply: a wait keeps its server slot until it returns, so a lag event consumes one server connection per waiting reader, which is when you have the most of them; and the wait and the read still have to reach the same node, so a pooler sitting in front of a load-balanced multi-replica endpoint breaks the pattern.</li>
</ul>
The pooler is the one component that already knows where each query is going, so it would be the natural place for this. But WAIT FOR</code> is a statement, which means a pooler would have to parse SQL or gain explicit support for it. The proposed wait_for_lsn</code> parameter would help here, dropping the round trip to fetch the LSN and letting a read carry its own position; at the time of writing that discussion is stale.</div>
Two constraints apply to any integration: WAIT FOR</code> never runs inside a function, procedure, or DO block, and never in a transaction above READ COMMITTED. Try the second and you get cannot be executed within a transaction with an isolation level higher than READ COMMITTED</code>. Both come down to snapshots. The wait has to run without one, because a snapshot held on a standby can block the replay that the wait is waiting for, at which point neither side moves. It is a utility statement for the same reason VACUUM</code> is one.</p>
Running it yourself</a>
</h2>
Everything above is in github.com/boringSQL/read-your-writes</a>. setup.sh</code> builds the pair from nothing, experiments.sh</code> produces the routing table and the timeout budgets, durability.sh</code> is the synchronous-commit comparison, and lsn-trap.sh</code> is the forty bytes. The Rails and Laravel suites are under frameworks/</code>, with a README of what each one caught.</p>
One loose end I could not close. During initial testing, with the replica 500 ms behind, I noticed four or five consecutive runs. In each, WAIT FOR showed success, but the row remained invisible for a few hundred milliseconds. This happened at both isolation levels and within or outside a transaction. The clean re-runs, with server-side timestamps, show the wait matching the set delay. The row appears as soon as it returns. I cannot reproduce the earlier behaviour and I cannot explain it. I'm betting on my own clocks. The first runs mixed host and container time. Also, recovery_min_apply_delay is known to delay commit records. This is the exact behaviour the pattern requires. I'm not sure about this one result. The harness is in the repo if anyone wants to take a closer look.</p>
boringSQL | Supercharge your SQL & PostgreSQL powers - replication

Read your own writes, off the primary
