Introduction

TiDB lets you tune runtime behavior through system variables, and tidb_replica_read is one of the most practical knobs for read traffic distribution. Changing it is easy at the SQL level, but safe operation requires clear scope control, measurement, and rollback planning. This guide shows how to update global settings confidently and verify the result in real workloads.

Core Sections

Understand What tidb_replica_read Controls

tidb_replica_read affects where read requests are sent in a replicated TiDB cluster. Typical values are leader, follower, and leader-and-follower.

• leader: reads are routed to leader replicas, usually strongest consistency behavior.
• follower: reads can be served by followers, often helping leader pressure but potentially exposing lag effects.
• leader-and-follower: mixed strategy for balancing load.

Before changing values, confirm your application tolerance for stale reads and the current replication health.

Inspect Current State First

Capture both global and session values. This gives a baseline and avoids confusion during testing.

SHOW GLOBAL VARIABLES LIKE 'tidb_replica_read';
SHOW SESSION VARIABLES LIKE 'tidb_replica_read';

Global value is the default for new sessions. Existing sessions can keep their current session setting until changed.

It is also useful to snapshot related variables around consistency and transaction behavior so your change review has full context.

Change Global Default Safely

Set the global value from a privileged SQL session.

SET GLOBAL tidb_replica_read = 'leader-and-follower';
SHOW GLOBAL VARIABLES LIKE 'tidb_replica_read';

After this, open a new connection and verify that it receives the new default.

SHOW SESSION VARIABLES LIKE 'tidb_replica_read';

If a client uses connection pooling, some sessions may remain long-lived, so rollout can appear partial until pools recycle.

Apply Session Value for Controlled Tests

For targeted query testing, set session scope only. This is useful in canary checks before global rollout.

SET SESSION tidb_replica_read = 'follower';
SHOW SESSION VARIABLES LIKE 'tidb_replica_read';

Run representative read queries and compare latency, error rates, and result freshness against baseline.

Measure Impact Instead of Assuming Improvement

Replica-read tuning can help or hurt depending on workload shape. Measure at least:

1. read latency percentiles
2. follower replica load distribution
3. replication lag indicators
4. application-level correctness checks for freshness-sensitive features

If your traffic includes strict read-after-write expectations, a more follower-heavy strategy may require endpoint-level routing decisions rather than one global default.

Change Management Pattern

Use a repeatable, auditable pattern for each variable change:

1-- 1) record current value
2SHOW GLOBAL VARIABLES LIKE 'tidb_replica_read';
3
4-- 2) apply target state
5SET GLOBAL tidb_replica_read = 'follower';
6
7-- 3) verify global and fresh session
8SHOW GLOBAL VARIABLES LIKE 'tidb_replica_read';

Operationally, pair this with ticket IDs, timestamped notes, and monitoring screenshots so future incidents can correlate behavior shifts with config changes.

Rollback Plan

Define rollback before rollout. A fast rollback statement is often enough for runtime issues.

SET GLOBAL tidb_replica_read = 'leader';

Make sure on-call engineers know the target rollback value and the expected stabilization window after reverting.

Persistence and Deployment Hygiene

Depending on variable type and deployment model, runtime SQL changes may interact with automation or startup configuration. Keep a single source of truth in your infrastructure workflow so values are not silently overwritten later.

In managed environments, review platform-specific behavior for configuration persistence and policy controls before relying only on ad hoc SQL changes.

Common Pitfalls

• Setting GLOBAL and expecting all currently open pooled sessions to change immediately.
• Enabling follower-heavy reads without checking replication lag and freshness requirements.
• Comparing performance without capturing pre-change baseline metrics.
• Rolling out cluster-wide changes directly in production without session-level canary testing.
• Making runtime SQL changes that conflict with infrastructure automation state.

Summary

• tidb_replica_read is a useful control for read routing, but it should be tuned with measurements.
• Always inspect existing global and session values before and after changes.
• Use session-level tests first, then update global defaults in a controlled rollout.
• Monitor latency, load distribution, and freshness-sensitive behavior during rollout.
• Keep rollback commands and configuration ownership clear to avoid drift.