Follower Read Fallback Behavior
In YugabyteDB (YSQL), there is currently no user-configurable Grand Unified Configuration (GUC) or admin command to tune the internal replication lag threshold that triggers a fallback from a follower to the leader during a follower read. The decision to redirect a query to the leader is handled by internal heuristics designed to prevent excessive staleness, but these thresholds are not exposed as tunable parameters for operators.
Current State of Observability and Tuning
Because the internal threshold is opaque, operators cannot explicitly set a maximum staleness bound (e.g., "fallback if lag > 100ms") via standard YSQL configuration. There is no direct metric that explicitly signals "fallback triggered" for a specific query in the standard logs without enabling deep debug tracing.
Predicting and Verifying Replication Lag
While you cannot tune the fallback trigger, you can monitor the actual replication lag to predict when followers may become too stale for your application's requirements. You can verify the current lag on a follower node using the following system function:
SELECT now() - pg_last_xact_replay_timestamp() AS replication_lag;
Practical Verification Steps:
- Monitor Lag: Regularly poll
pg_last_xact_replay_timestamp() on follower nodes to establish a baseline for your workload's typical lag.
- Test Visibility: Perform a write on the leader and immediately attempt a follower read. If the data is missing and the query is served by the follower, you are within the internal lag threshold. If the query is redirected to the leader, the internal threshold has been exceeded.
Assumptions and Constraints
This behavior assumes a standard YugabyteDB deployment using the YSQL layer. Because these heuristics are internal to the tablet server's coordination logic, they may vary between minor versions. If your application requires a strict "read-your-writes" guarantee, the recommended approach is to route those specific critical reads to the leader explicitly rather than relying on the follower-read fallback mechanism.
Missing Diagnostic Detail: To provide a more precise recommendation, please specify the YugabyteDB version you are running, as internal consistency heuristics are subject to change across major releases.
yugabytedb