Guarantee Read-Your-Writes Consistency
Route a user's reads to the primary after a write, or carry a version token, so a user never sees their own change vanish on a replica.
Task
Provide read-your-writes consistency for a user session while still offloading most reads to replicas.
When to use this
A user updates their profile, the page reloads from a replica that has not caught up, and the change appears to have failed.
Prerequisites
- A primary and one or more replicas
- A session or request context to carry the token
Steps
1. After a write, record the write timestamp or version in the user session.
Expected output: The session knows how fresh this user data must be.
2. Route reads to the primary when the session requires freshness; otherwise use a replica.
Expected output: Recent writers always read their own data.
3. Expire the sticky-to-primary window after replication lag is comfortably exceeded.
Expected output: Traffic returns to replicas, protecting capacity.
4. Alternatively, track the replica replay position and only read when it has passed the write position.
psql -c "SELECT pg_last_wal_replay_lsn();"Expected output: Consistency is enforced by position, not guesswork.
Troubleshooting
Problem
All reads stick to primary forever
Solution
Expire the window based on measured replication lag so capacity recovers.
Problem
Clock-based windows are unreliable
Solution
Use a monotonic version or a replication position rather than wall-clock comparison across hosts.
Limitations
- Read-your-writes is per user; it does not give global consistency and should not be used where all readers must see the same value.
- Position tracking requires replica support for the underlying position mechanism.
Context
Provide read-your-writes consistency for a user session while still offloading most reads to replicas. A user updates their profile, the page reloads from a replica that has not caught up, and the change appears to have failed.
Steps
- After a write, record the write timestamp or version in the user session. Expected: The session knows how fresh this user data must be.
- Route reads to the primary when the session requires freshness; otherwise use a replica. Expected: Recent writers always read their own data.
- Expire the sticky-to-primary window after replication lag is comfortably exceeded. Expected: Traffic returns to replicas, protecting capacity.
- Alternatively, track the replica replay position and only read when it has passed the write position. Expected: Consistency is enforced by position, not guesswork.
const fresh = session.lastWriteAt && Date.now() - session.lastWriteAt < 5000;
const conn = fresh ? primary : replicaPool.pick();Verify
- The session knows how fresh this user data must be.
- Recent writers always read their own data.
- Traffic returns to replicas, protecting capacity.
- Consistency is enforced by position, not guesswork.
Limits
- Read-your-writes is per user; it does not give global consistency and should not be used where all readers must see the same value.
- Position tracking requires replica support for the underlying position mechanism.