From f518aca15809775d160d59c9094cb877ddc38a86 Mon Sep 17 00:00:00 2001 From: zyguan Date: Tue, 29 Jul 2025 02:30:40 +0000 Subject: [PATCH 1/8] Update follower read and learner read descriptions Signed-off-by: zyguan --- follower-read.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/follower-read.md b/follower-read.md index 6a8f413bea93e..33aaed21dea03 100644 --- a/follower-read.md +++ b/follower-read.md @@ -32,7 +32,7 @@ Default: leader This variable is used to set the expected data read mode. - When the value of `tidb_replica_read` is set to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. -- When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations. +- When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations. When a Region has learner replicas, TiDB also considers reading data from learner replicas. In this case, follower replicas and learner replicas have the same priority. If there are no available follower or learner replicas in the current Region, TiDB will read from the leader replica. - When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower. - When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations. - When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica. @@ -41,13 +41,18 @@ This variable is used to set the expected data read mode. - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations. - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations. -- When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no learner replica in the Region, TiDB returns an error. +- When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no available learner replica in the Region, TiDB will read data from available leader or follower replicas. > **Note:** > > When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). +> +> For TiDB versions up to and including v7.5: +> +> - When the value of `tidb_replica_read` is set to `follower` and no follower or learner replicas are available, TiDB returns an error. +> - When the value of `tidb_replica_read` is set to `learner` and no learner replicas are available, TiDB returns an error. From 2d30cc11d8513356079e250c7209a6ef19981031 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Thu, 11 Sep 2025 17:00:32 +0800 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- follower-read.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/follower-read.md b/follower-read.md index 33aaed21dea03..b225bf0d41e8f 100644 --- a/follower-read.md +++ b/follower-read.md @@ -31,8 +31,8 @@ Default: leader This variable is used to set the expected data read mode. -- When the value of `tidb_replica_read` is set to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. -- When the value of `tidb_replica_read` is set to `follower`, TiDB selects a follower replica of the Region to perform all read operations. When a Region has learner replicas, TiDB also considers reading data from learner replicas. In this case, follower replicas and learner replicas have the same priority. If there are no available follower or learner replicas in the current Region, TiDB will read from the leader replica. +- When yu set the value of `tidb_replica_read` to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. +- When you set the value of `tidb_replica_read` to `follower`, TiDB selects a follower replica of the Region to perform read operations. If the Region has learner replicas, TiDB also considers them for reads with the same priority. If no available follower or learner replicas exist in the current Region, TiDB reads from the leader replica. - When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower. - When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations. - When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica. @@ -41,7 +41,7 @@ This variable is used to set the expected data read mode. - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations. - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations. -- When the value of `tidb_replica_read` is set to `learner`, TiDB reads data from the learner replica. If there is no available learner replica in the Region, TiDB will read data from available leader or follower replicas. +- When you set the value of `tidb_replica_read` to `learner`, TiDB reads data from the learner replica. If no learner replica is available in the Region, TiDB reads from an available leader or follower replica. @@ -51,8 +51,8 @@ This variable is used to set the expected data read mode. > > For TiDB versions up to and including v7.5: > -> - When the value of `tidb_replica_read` is set to `follower` and no follower or learner replicas are available, TiDB returns an error. -> - When the value of `tidb_replica_read` is set to `learner` and no learner replicas are available, TiDB returns an error. +- If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. +- If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error. From 5995aa8b3d5c757d812e604e40f84fb86713496f Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Sep 2025 15:04:26 +0800 Subject: [PATCH 3/8] Update follower-read.md --- follower-read.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/follower-read.md b/follower-read.md index b225bf0d41e8f..7ebaf8dad1255 100644 --- a/follower-read.md +++ b/follower-read.md @@ -48,9 +48,9 @@ This variable is used to set the expected data read mode. > **Note:** > > When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). -> -> For TiDB versions up to and including v7.5: -> + +For TiDB versions up to and including v7.5: + - If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. - If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error. From bb4ed07a721c5cea02ba0b6181fc093207e645d3 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Mon, 15 Sep 2025 19:34:00 +0800 Subject: [PATCH 4/8] Update follower-read.md --- follower-read.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/follower-read.md b/follower-read.md index 7ebaf8dad1255..b59478fd734a5 100644 --- a/follower-read.md +++ b/follower-read.md @@ -48,11 +48,11 @@ This variable is used to set the expected data read mode. > **Note:** > > When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). - -For TiDB versions up to and including v7.5: - -- If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. -- If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error. +> +> For TiDB versions up to and including v7.5: +> +> - If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. +> - If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error. From cdef4ad33ab7c75c47ef8154cc27954acf1effbf Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 16 Sep 2025 07:35:50 +0800 Subject: [PATCH 5/8] Update follower-read.md --- follower-read.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/follower-read.md b/follower-read.md index b59478fd734a5..abe512bf6dd13 100644 --- a/follower-read.md +++ b/follower-read.md @@ -49,7 +49,7 @@ This variable is used to set the expected data read mode. > > When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). > -> For TiDB versions up to and including v7.5: +> For TiDB v7.5 and earlier versions: > > - If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. > - If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error. From 144745c016a0c057f6670a25c49f7292838f7fd3 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Tue, 16 Sep 2025 07:37:28 +0800 Subject: [PATCH 6/8] Update follower-read.md --- follower-read.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/follower-read.md b/follower-read.md index abe512bf6dd13..5fd85f6b3a011 100644 --- a/follower-read.md +++ b/follower-read.md @@ -47,7 +47,7 @@ This variable is used to set the expected data read mode. > **Note:** > -> When the value of `tidb_replica_read` is set to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). +> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). > > For TiDB v7.5 and earlier versions: > From a3e06bd4fd5c580c591352640cce4b3bca159b23 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 19 Sep 2025 16:12:14 +0800 Subject: [PATCH 7/8] Update follower-read.md --- follower-read.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/follower-read.md b/follower-read.md index 5fd85f6b3a011..87f40e3e01401 100644 --- a/follower-read.md +++ b/follower-read.md @@ -47,7 +47,7 @@ This variable is used to set the expected data read mode. > **Note:** > -> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/v1.4/configure-a-tidb-cluster#high-availability-of-data). +> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data). > > For TiDB v7.5 and earlier versions: > From aec9afc18b26ae094bbe3e264befb189326263a1 Mon Sep 17 00:00:00 2001 From: xixirangrang Date: Fri, 19 Sep 2025 16:52:12 +0800 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Grace Cai --- follower-read.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/follower-read.md b/follower-read.md index 87f40e3e01401..76156e996f61a 100644 --- a/follower-read.md +++ b/follower-read.md @@ -31,8 +31,8 @@ Default: leader This variable is used to set the expected data read mode. -- When yu set the value of `tidb_replica_read` to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. -- When you set the value of `tidb_replica_read` to `follower`, TiDB selects a follower replica of the Region to perform read operations. If the Region has learner replicas, TiDB also considers them for reads with the same priority. If no available follower or learner replicas exist in the current Region, TiDB reads from the leader replica. +- When you set the value of `tidb_replica_read` to `leader` or an empty string, TiDB maintains its default behavior and sends all read operations to the leader replica to perform. +- When you set the value of `tidb_replica_read` to `follower`, TiDB selects a follower replica of the Region to perform read operations. If the Region has learner replicas, TiDB also considers them for reads with the same priority. If no available follower or learner replicas exist for the current Region, TiDB reads from the leader replica. - When the value of `tidb_replica_read` is set to `leader-and-follower`, TiDB can select any replicas to perform read operations. In this mode, read requests are load balanced between the leader and follower. - When the value of `tidb_replica_read` is set to `prefer-leader`, TiDB prefers to select the leader replica to perform read operations. If the leader replica is obviously slow in processing read operations (such as caused by disk or network performance jitter), TiDB will select other available follower replicas to perform read operations. - When the value of `tidb_replica_read` is set to `closest-replicas`, TiDB prefers to select a replica in the same availability zone to perform read operations, which can be a leader or a follower. If there is no replica in the same availability zone, TiDB reads from the leader replica. @@ -41,15 +41,15 @@ This variable is used to set the expected data read mode. - If the estimated result of a read request is greater than or equal to the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB prefers to select a replica in the same availability zone for read operations. To avoid unbalanced distribution of read traffic across availability zones, TiDB dynamically detects the distribution of availability zones for all online TiDB and TiKV nodes. In each availability zone, the number of TiDB nodes whose `closest-adaptive` configuration takes effect is limited, which is always the same as the number of TiDB nodes in the availability zone with the fewest TiDB nodes, and the other TiDB nodes automatically read from the leader replica. For example, if TiDB nodes are distributed across 3 availability zones (A, B, and C), where A and B each contains 3 TiDB nodes and C contains only 2 TiDB nodes, the number of TiDB nodes whose `closest-adaptive` configuration takes effect in each availability zone is 2, and the other TiDB node in each of the A and B availability zones automatically selects the leader replica for read operations. - If the estimated result of a read request is less than the value of [`tidb_adaptive_closest_read_threshold`](/system-variables.md#tidb_adaptive_closest_read_threshold-new-in-v630), TiDB can only select the leader replica for read operations. -- When you set the value of `tidb_replica_read` to `learner`, TiDB reads data from the learner replica. If no learner replica is available in the Region, TiDB reads from an available leader or follower replica. +- When you set the value of `tidb_replica_read` to `learner`, TiDB reads data from the learner replica. If no learner replica is available for the current Region, TiDB reads from an available leader or follower replica. > **Note:** > -> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, you need to configure the cluster to ensure that replicas are distributed across availability zones according to the specified configuration. To configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV, refer to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data). +> When you set `tidb_replica_read` to `closest-replicas` or `closest-adaptive`, to ensure that replicas are distributed across availability zones according to the specified configuration, you need to configure `location-labels` for PD and set the correct `labels` for TiDB and TiKV according to [Schedule replicas by topology labels](/schedule-replicas-by-topology-labels.md). TiDB depends on the `zone` label to match TiKV nodes in the same availability zone, so you need to make sure that the `zone` label is included in the `location-labels` of PD and `zone` is included in the configuration of each TiDB and TiKV node. If your cluster is deployed using TiDB Operator, refer to [High availability of data](https://docs.pingcap.com/tidb-in-kubernetes/stable/configure-a-tidb-cluster#high-availability-of-data). > -> For TiDB v7.5 and earlier versions: +> For TiDB v7.5.0 and earlier versions: > > - If you set `tidb_replica_read` to `follower` and no follower or learner replicas are available, TiDB returns an error. > - If you set `tidb_replica_read` to `learner` and no learner replicas are available, TiDB returns an error.