Use YugabyteDB follower reads for catalog traffic while keeping inventory strong

The problem: a global catalog that waits on a distant leader

Imagine an e-commerce application running in us-west while its YugabyteDB tablet leaders live in us-east. Every product-listing query crosses regions, adding round-trip latency. Inventory updates must be strictly consistent and can afford the leader round-trip, but catalog pages do not need the same guarantee. The decision is not strong consistency everywhere versus fast reads everywhere. It is splitting the workload: reads from nearby followers with bounded staleness, writes through the leader with linearizable consistency.

YugabyteDB replicates each table as one or more tablets using the Raft consensus algorithm. By default, only the tablet leader serves reads, which guarantees linearizable results but forces remote clients to wait for cross-region round trips. Follower reads let a follower replica serve a read if its applied state is recent enough, tracked with hybrid logical clocks (HLC) and exposed as a safe-time value.

Consistency modes and where to set them

YugabyteDB supports three consistency levels:

• STRONG: reads go to the leader only; linearizable.
• BOUNDED_STALENESS: reads may go to a follower whose safe-time is within a configured staleness bound; the default bound is commonly 15 seconds.
• EVENTUAL: reads may go to any follower with no staleness bound.

Applications choose a level per transaction or per session with SET yb_consistency_level. The staleness bound itself is tuned with yb_follower_read_staleness_ms. These are session settings, so they do not require a cluster restart, but they also do not persist beyond the connection.

Worked example: catalog listing versus inventory decrement

Run these statements in a YugabyteDB-aware SQL client connected to any cluster node. The connecting user needs SELECT on products and UPDATE on inventory.

-- Session 1: product catalog page. A five-second-old price is acceptable.
SET yb_consistency_level = 'BOUNDED_STALENESS';
SET yb_follower_read_staleness_ms = 5000;

SELECT sku, title, price
FROM products
WHERE region = 'us-west'
ORDER BY title
LIMIT 20;

-- Session 2: checkout inventory. This must reflect the latest committed write.
SET yb_consistency_level = 'STRONG';

UPDATE inventory
SET quantity = quantity - 1
WHERE sku = 'ABC-123'
RETURNING quantity;

Expected check: the catalog SELECT should be served by a local follower if one is within the five-second bound; the inventory UPDATE always routes to the leader. Risk: if the follower's replication lag exceeds five seconds, reads fall back to the leader, so latency returns to the cross-region baseline for that query. Statements such as SELECT ... FOR UPDATE always route to the leader because they require row locks.

Operational trade-offs and limits

• Staleness window. With BOUNDED_STALENESS, a product page can show a price or stock count up to the configured bound old. Do not use it for checkout, balance checks, or idempotency-key validation.
• Replica health. If a follower lags beyond the bound because of network partition or disk saturation, reads fall back to the leader. Correctness is preserved, but latency is not.
• Quorum safety. In a replication factor of 3 cluster with only two live replicas, follower reads are disabled automatically.
• Driver awareness. Generic PostgreSQL drivers may not know about follower endpoints and can send all traffic to the leader. Use an official YugabyteDB-aware driver.

Verify before you depend on follower reads

1. Confirm tablet placement with yb-admin, run on a cluster admin node with shell access:

yb-admin -master_addresses [MASTER1]:7100,[MASTER2]:7100,[MASTER3]:7100 get_tablet_locations [TABLE_NAME_OR_ID]

Look for LEADER and FOLLOWER roles across regions. If no follower exists in the client's region, follower reads cannot reduce latency there.

1. Inspect the query plan to see whether the planner expects a follower scan:

EXPLAIN ANALYZE SELECT * FROM products WHERE sku = 'ABC-123';

The plan should reference the tablet and replica being scanned, though exact wording varies by version.

1. Monitor replication lag. Alert on sustained high values in the follower-read staleness histogram; persistent elevation means followers are falling behind and reads will fall back to leaders.

Closing

Start by routing only read-heavy, tolerance-for-stale-data paths—catalogs, recommendations, dashboards—to BOUNDED_STALENESS with a bound tuned to the feature, not the default 15 seconds. Keep financial and inventory-mutation paths on STRONG. Verify tablet placement and staleness metrics before promoting the pattern to production, and treat follower reads as a latency optimization, not a consistency guarantee.