Read-After-Write Consistency: Handling PostgreSQL Replication Lag in Distributed Django Apps

The Replica Lag Dilemma in Modern Web Architectures

As web platforms grow beyond a few thousand concurrent requests per second, offloading read-heavy queries to physical PostgreSQL read replicas is one of the most effective scaling patterns available. By directing SELECT queries to one or more replicas, the primary database instance is freed to handle high-priority write transactions, row-level locks, and financial ledger updates.

However, asynchronous physical streaming replication introduces a classic distributed systems challenge: replication lag. Under network fluctuations, heavy write bursts, or bulk analytical queries on the replica, the replica may trail behind the primary by 50ms to 500ms. If a user submits a form (POST) to update their user profile or create a blog post, and the application immediately redirects them (GET) to view the updated resource, a query dispatched to a lagging replica returns old state or a 404 Not Found error. The user frantically clicks submit again, believing the system failed.

1. Architectural Consistency Models

To eliminate read-after-write inconsistencies without funneling 100% of read traffic back to the primary database, modern systems apply one of three consistency patterns:

2. Designing the Session-Pinned Sticky Database Router

Django provides a flexible database routing framework via db_for_read and db_for_write hooks. We can combine a custom thread-local or request-scoped middleware with Django's database router to track user write timestamps and route subsequent reads accordingly:

# core/routers.py
import time
from threading import local
from django.conf import settings

_thread_local = local()

def set_write_timestamp(timestamp=None):
    # Mark that the current request/session executed a write transaction.
    _thread_local.last_write_time = timestamp or time.time()

def get_write_timestamp():
    return getattr(_thread_local, 'last_write_time', 0)

class StickyPrimaryReplicaRouter:
    # Intelligent database router providing Read-After-Write consistency:
    # - Writes always route to 'default' (Primary).
    # - Reads route to 'default' if a write occurred within STICKY_WINDOW seconds.
    # - All other reads distribute across read replicas.
    STICKY_WINDOW_SECONDS = getattr(settings, 'DB_STICKY_REPLICA_WINDOW', 3.0)

    def db_for_read(self, model, **hints):
        # Force write master if explicit hint provided
        if hints.get('use_master'):
            return 'default'

        now = time.time()
        last_write = get_write_timestamp()
        
        # If user executed a write within the sticky window, pin read to primary
        if (now - last_write) < self.STICKY_WINDOW_SECONDS:
            return 'default'

        # Route to read replica pool
        return 'replica'

    def db_for_write(self, model, **hints):
        set_write_timestamp()
        return 'default'

    def allow_relation(self, obj1, obj2, **hints):
        return True

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return db == 'default'

3. Sticky Session Middleware Implementation

To persist this write token across HTTP redirects (e.g. POST → 302 Redirect → GET), store the timestamp in the user's signed cookie or session cache:

# core/middleware.py
import time
from .routers import set_write_timestamp

class ReadAfterWriteConsistencyMiddleware:
    COOKIE_NAME = 'dev_last_write'
    STICKY_WINDOW = 3.0  # seconds

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # Check if incoming request carries a recent write cookie
        cookie_val = request.COOKIES.get(self.COOKIE_NAME)
        if cookie_val:
            try:
                last_write = float(cookie_val)
                if (time.time() - last_write) < self.STICKY_WINDOW:
                    set_write_timestamp(last_write)
            except ValueError:
                pass

        response = self.get_response(request)

        # If this request executed a write (e.g. POST/PUT/DELETE/PATCH), set cookie
        if request.method in ('POST', 'PUT', 'PATCH', 'DELETE'):
            now = time.time()
            response.set_cookie(
                self.COOKIE_NAME,
                str(now),
                max_age=int(self.STICKY_WINDOW + 2),
                httponly=True,
                samesite='Lax',
                secure=not settings.DEBUG
            )

        return response

4. Monitoring Replication Lag at the PostgreSQL Layer

Never rely solely on application heuristics. Regularly verify that your read replica's physical byte lag remains within acceptable thresholds by querying pg_stat_replication on the primary:

SELECT
    client_addr,
    application_name,
    state,
    sync_state,
    ROUND(pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) / (1024 * 1024), 2) AS lag_mb,
    EXTRACT(EPOCH FROM (clock_timestamp() - replay_ts)) AS lag_seconds
FROM pg_stat_replication;

When lag_seconds exceeds 1.5 seconds, trigger Prometheus or Vector telemetry alerts to investigate saturated network links or heavy disk locks on the replica. For real-time monitoring and observability setup, see our guide on Zero-Cost Production Observability.

Production Engineering Takeaways

• Eliminate ghost 404s: Session-pinned routing guarantees users always see their own updates without globally overloading the primary database.
• Keep sticky windows tight: A 2-to-3 second window is more than enough to cover typical HTTP redirects while returning 95%+ of subsequent reads to replicas.
• Combine with explicit query hints: Allow mission-critical queries (such as payment verification or balance checks) to explicitly specify .using('default'). See our related publication on Preventing Concurrency Race Conditions.