From f25978799cba808bc6af450c5af7b69dbe1d82f7 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sun, 20 Sep 2026 16:39:16 +0800 Subject: [PATCH 1/6] This is an automated cherry-pick of #23905 Signed-off-by: ti-chi-bot --- tiproxy/tiproxy-configuration.md | 173 +++++++++++++++++++++++++++++++ tiproxy/tiproxy-grafana.md | 1 + tiproxy/tiproxy-load-balance.md | 26 ++--- tiproxy/tiproxy-overview.md | 4 +- 4 files changed, 190 insertions(+), 14 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index 59016b73f0e74..2b7ee8d29701e 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -67,12 +67,39 @@ Configuration for SQL port. + Unit: second + When TiProxy shuts down, it closes connections when they have completed their current transactions (also known as draining clients) within `graceful-close-conn-timeout` seconds. After that, all the connections are closed at once. `graceful-close-conn-timeout` happens after `graceful-wait-before-shutdown`. It is recommended to set this timeout longer than the lifecycle of a transaction. +#### `fail-backend-list` New in v1.3.3 + ++ Default value: `[]` ++ Hot-reload supported: Yes ++ Specifies the list of backends to remove from routing. After confirming that a TiDB server has failed, you can add it to this list. TiProxy stops routing new connections to these backends and migrates existing connections away from them. Each item in the list can be in one of the following two forms: + + - Backend Pod name, for example, `"db-tidb-0"` + - Backend address in the format of `:`, for example, `"10.0.0.10:4000"` + ++ If applying this list would leave no routable backends, TiProxy ignores this list to ensure that requests can still be routed. + +#### `failover-timeout` New in v1.3.3 + ++ Default value: `60` ++ Hot-reload supported: Yes ++ Unit: seconds ++ Range: `>= 0` ++ When a backend appears in [`fail-backend-list`](#fail-backend-list-new-in-v133), TiProxy migrates existing connections away from that backend. If there are still remaining connections on that backend after `failover-timeout` seconds, TiProxy forcibly closes these connections. `0` means to forcibly close the remaining connections immediately. + #### `max-connections` + Default value: `0` + Support hot-reload: yes + Each TiProxy instance can accept `max-connections` connections at most. `0` means no limitation. +#### `high-memory-usage-reject-threshold` New in v1.3.3 + ++ Default value: `0.9` ++ Hot-reload supported: Yes ++ Range: `[0, 1]` ++ When TiProxy's memory usage reaches or exceeds this threshold, TiProxy rejects new connections, and the status port returns an unhealthy status. Existing connections are not affected. If [`ha.virtual-ip`](#virtual-ip) is configured, the instance also releases the virtual IP. For example, `0.9` means that it takes effect when memory usage reaches 90%. ++ `0` means not rejecting new connections due to memory usage. If the configured value is greater than `0` and less than `0.5`, TiProxy adjusts it to `0.5`. + #### `conn-buffer-size` + Default value: `32768` @@ -128,6 +155,138 @@ Configurations for the load balancing policy of TiProxy. + Possible values: `resource`, `location`, `connection` + Specifies the load balancing policy. For the meaning of each possible value, see [TiProxy load balancing policies](/tiproxy/tiproxy-load-balance.md#configure-load-balancing-policies). +<<<<<<< HEAD +======= +#### `routing-policy` New in v1.3.3 + ++ Default value: `prefer-idle` ++ Hot-reload supported: Yes ++ Possible values: `prefer-idle`, `random`, `idlest` ++ Specifies the routing policy for new connections: + + - `prefer-idle`: Excludes backends that need connection migration, and then randomly selects from the remaining routable backends. Suitable for most scenarios. + - `random`: Randomly selects from routable backends, where the idlest backend has a slightly higher probability of being selected. Suitable for scenarios where new connections are created more intensively. + - `idlest`: Always routes new connections to the idlest routable backend. Suitable for scenarios with long-lived connections and infrequent connection creation. + +#### `status` New in v1.3.3 + +Status-based load balancing configuration. + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Range: `>= 0` ++ Specifies the number of connections migrated per second for status-based load balancing. `0` means that TiProxy automatically calculates the migration rate based on the current number of connections. When a TiDB server is shutting down, you can increase this value appropriately to speed up connection migration. + +#### `health` New in v1.3.3 + +Health-based load balancing configuration. It takes effect only when [`policy`](#policy) is `resource` or `location`. + +##### `enabled` New in v1.3.3 + ++ Default value: `true` ++ Hot-reload supported: Yes ++ Whether to enable [health-based load balancing](/tiproxy/tiproxy-load-balance.md#health-based-load-balancing). + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Range: `>= 0` ++ Specifies the number of connections migrated per second for health-based load balancing. `0` indicates that TiProxy automatically calculates the migration rate. + +#### `memory` New in v1.3.3 + +Configuration for memory-based load balancing. This item takes effect only when [`policy`](#policy) is `resource` or `location`. + +##### `enabled` New in v1.3.3 + ++ Default value: `true` ++ Hot-reload supported: Yes ++ Whether to enable [memory-based load balancing](/tiproxy/tiproxy-load-balance.md#memory-based-load-balancing). + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Range: `>= 0` ++ Specifies the number of connections migrated per second for memory-based load balancing. `0` indicates that TiProxy automatically calculates the migration rate. + +#### `cpu` New in v1.3.3 + +Configuration for CPU-based load balancing. This item takes effect only when [`policy`](#policy) is `resource` or `location`. + +##### `enabled` New in v1.3.3 + ++ Default value: `true` ++ Hot-reload supported: Yes ++ Whether to enable [CPU-based load balancing](/tiproxy/tiproxy-load-balance.md#cpu-based-load-balancing). + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Range: `>= 0` ++ Specifies the number of connections migrated per second for CPU-based load balancing. `0` indicates that TiProxy automatically calculates the migration rate. It is not recommended to set this value too high when CPU hotspots are unstable, to avoid repeated connection migrations. + +##### `min-balance-usage` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Range: `[0, 1]` ++ When the CPU usage of the source backend is lower than this threshold, CPU-based connection migration is not triggered. For example, `0.2` means no migration is performed when the CPU usage of the source backend is lower than 20%. + +##### `max-usage-gap` New in v1.3.3 + ++ Default value: `1` ++ Hot-reload supported: Yes ++ Value range: `0` or `[0.05, 1]` ++ Specifies the minimum CPU usage difference required to trigger CPU-based connection migration. Migration is triggered when the CPU usage difference between the source backend and the target backend reaches this threshold. For example, `0.1` means migration can be triggered when the difference reaches 10%. The default value `1` means whether to migrate depends only on adaptive rules. If you need more balanced CPU usage across backends, you can reduce this value appropriately. + +#### `location` New in v1.3.3 + +Configuration for location-based load balancing. This item takes effect only when [`policy`](#policy) is `resource` or `location`. + +##### `enabled` New in v1.3.3 + ++ Default value: `true` ++ Hot-reload supported: Yes ++ Whether to enable [location-based load balancing](/tiproxy/tiproxy-load-balance.md#location-based-load-balancing). + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Value range: `>= 0` ++ Specifies the number of connections migrated per second for location-based load balancing. `0` means the default migration rate is used (1 connection per second). + +#### `conn-count` New in v1.3.3 + +Configuration for connection-count-based load balancing. + +##### `migrations-per-second` New in v1.3.3 + ++ Default value: `0` ++ Hot-reload supported: Yes ++ Value range: `>= 0` ++ Specifies the number of connections migrated per second for connection-count-based load balancing. `0` means TiProxy automatically calculates the migration rate. If you observe connections frequently migrating back and forth, you can reduce this value appropriately. + +##### `count-ratio-threshold` New in v1.3.3 + ++ Default value: `1.2` ++ Hot-reload supported: Yes ++ Value range: `0` or `> 1` ++ Specifies the connection count ratio threshold for triggering connection-count-based migration. When the ratio of the backend with the most connections to the backend with the fewest connections exceeds this threshold, TiProxy starts migrating connections. Increasing this value can reduce migration frequency. + +### `enable-traffic-replay` + ++ Default value: `true` ++ Support hot-reload: yes ++ Possible values: `true`, `false` ++ Specifies whether to enable [traffic replay](/tiproxy/tiproxy-traffic-replay.md). If it is set to `false`, traffic capture and replay operations will result in errors. + +>>>>>>> f9f08f3606 (Update TiProxy to v1.3.3 (#23905)) ### ha High availability configurations for TiProxy. @@ -161,6 +320,20 @@ Starting from v1.3.1, TiProxy supports configuring multiple virtual IP addresses + Support hot-reload: no + Specifies the network interface to bind the virtual IP to, such as `"eth0"`. The virtual IP will be bound to a TiProxy instance only when both [`ha.virtual-ip`](#virtual-ip) and `ha.interface` are set. +#### `garp-burst-count` New in v1.3.3 + ++ Default value: `5` ++ Hot-reload supported: No ++ Value range: `>= 0` ++ Specifies the number of GARP (Gratuitous ARP) packets sent immediately after a TiProxy instance takes over and binds the virtual IP. GARP is used to notify switches and hosts to update the MAC address corresponding to the virtual IP, so that client traffic can be switched to the TiProxy instance that has taken over the virtual IP as soon as possible. Sending multiple packets continuously can reduce the risk of switchover delay caused by the loss of the first GARP packet. `0` is automatically adjusted to `1`. + +#### `garp-refresh-count` New in v1.3.3 + ++ Default value: `30` ++ Hot-reload: No ++ Range: `>= 0` ++ Specifies the number of times to additionally send GARP after taking over the virtual IP. The interval between two sends is 1 second, and [`garp-burst-count`](#garp-burst-count-new-in-v133) packets are sent each time. This is used to refresh the previous virtual IP-to-MAC address mapping in upstream devices for a period of time after failover, to avoid traffic still being forwarded to the old instance. `0` means no additional packets are sent after takeover. + ### `labels` + Default value: `{}` diff --git a/tiproxy/tiproxy-grafana.md b/tiproxy/tiproxy-grafana.md index 2a8cf4c4a83db..0b08a15534b54 100644 --- a/tiproxy/tiproxy-grafana.md +++ b/tiproxy/tiproxy-grafana.md @@ -37,6 +37,7 @@ TiProxy has four panel groups. The metrics on these panels indicate the current - proxy error: other TiProxy errors - backend network break: fails to read from or write to the TiDB. This may be caused by a network problem or the TiDB server shutting down - backend handshake fail: TiProxy fails to handshake with the TiDB server +- Connection Lifetime: the average and P99 values of connection lifetime - Goroutine Count: the number of Goroutines on each TiProxy instance - Owner: the TiProxy instance that executes various tasks. For example, `10.24.31.1:3080 - vip` indicates that the TiProxy instance at `10.24.31.1:3080` is bound to a virtual IP. The tasks include the following: - vip: binds a virtual IP diff --git a/tiproxy/tiproxy-load-balance.md b/tiproxy/tiproxy-load-balance.md index c08bb9adcb032..215e3f567018b 100644 --- a/tiproxy/tiproxy-load-balance.md +++ b/tiproxy/tiproxy-load-balance.md @@ -9,20 +9,16 @@ TiProxy v1.0.0 only supports status-based and connection count-based load balanc By default, TiProxy applies these policies with the following priorities: -1. Status-based load balancing: when a TiDB server is shutting down, TiProxy migrates connections from that TiDB server to an online TiDB server. -2. Label-based load balancing: TiProxy prioritizes routing requests to TiDB servers that share the same label as the TiProxy instance, enabling resource isolation at the computing layer. +1. Label-based load balancing: TiProxy prioritizes routing connection requests to TiDB servers that share the same label as the TiProxy instance, enabling resource isolation at the computing layer. +2. Status-based load balancing: when a TiDB server cannot provide service normally or is shutting down, TiProxy migrates connections from that TiDB server to an online TiDB server. 3. Health-based load balancing: when the health of a TiDB server is abnormal, TiProxy migrates connections from that TiDB server to a healthy TiDB server. -4. Memory-based load balancing: when a TiDB server is at risk of running out of memory (OOM), TiProxy migrates connections from that TiDB server to a TiDB server with lower memory usage. +4. Memory-based load balancing: when a TiDB server is at risk of Out of Memory (OOM), TiProxy migrates connections from that TiDB server to a TiDB server with lower memory usage. 5. CPU-based load balancing: when the CPU usage of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with lower CPU usage. -6. Location-based load balancing: TiProxy prioritizes routing requests to the TiDB server geographically closest to TiProxy. +6. Location-based load balancing: TiProxy prioritizes routing requests to TiDB servers that are geographically closer to TiProxy. 7. Connection count-based load balancing: when the connection count of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with fewer connections. To adjust the priorities of load balancing policies, see [Configure load balancing policies](#configure-load-balancing-policies). -## Status-based load balancing - -TiProxy periodically checks whether a TiDB server is offline or shutting down using the SQL port and status port. - ## Label-based load balancing Label-based load balancing prioritizes routing connections to TiDB servers that share the same label as TiProxy, enabling resource isolation at the computing layer. This policy is disabled by default and should only be enabled when your workload requires computing resource isolation. @@ -100,6 +96,10 @@ pd_servers: - host: pd-host-3 ``` +## Status-based load balancing + +TiProxy periodically checks whether a TiDB server can provide services properly using the SQL port and status port, including whether it is offline or shutting down. + ## Health-based load balancing TiProxy determines the health of a TiDB server by querying its error count. When the health of a TiDB server is abnormal while others are normal, TiProxy migrates connections from that server to a healthy TiDB server, achieving automatic failover. @@ -189,7 +189,7 @@ In the preceding configuration, the TiProxy instance on `tiproxy-host-1` priorit ## Connection count-based load balancing -TiProxy migrates connections from a TiDB server with more connections to a server with fewer connections. This policy is not configurable and has the lowest priority. +TiProxy migrates connections from a TiDB server with more connections to a server with fewer connections. This policy has the lowest priority. Typically, TiProxy identifies the load on TiDB servers based on CPU usage. This policy usually takes effect in the following scenarios: @@ -200,9 +200,11 @@ Typically, TiProxy identifies the load on TiDB servers based on CPU usage. This TiProxy lets you configure the combination and priority of load balancing policies through the [`policy`](/tiproxy/tiproxy-configuration.md#policy) configuration item. -- `resource`: the resource priority policy performs load balancing based on the following priority order: status, label, health, memory, CPU, location, and connection count. -- `location`: the location priority policy performs load balancing based on the following priority order: status, label, location, health, memory, CPU, and connection count. -- `connection`: the minimum connection count policy performs load balancing based on the following priority order: status, label, and connection count. +- `resource`: the resource priority policy performs load balancing based on the following priority order: label, status, health, memory, CPU, location, and connection count. +- `location`: the location priority policy performs load balancing based on the following priority order: label, status, location, health, memory, CPU, and connection count. +- `connection`: the minimum connection count policy performs load balancing based on the following priority order: label, status, and connection count. + +For more configuration items related to load balancing, see [`balance`](/tiproxy/tiproxy-configuration.md#balance). ## More resources diff --git a/tiproxy/tiproxy-overview.md b/tiproxy/tiproxy-overview.md index 544f81beb6947..30abf22d31e25 100644 --- a/tiproxy/tiproxy-overview.md +++ b/tiproxy/tiproxy-overview.md @@ -141,7 +141,7 @@ The following steps describe how to deploy TiProxy when creating a new cluster. ```yaml component_versions: - tiproxy: "v1.3.2" + tiproxy: "v1.3.3" server_configs: tiproxy: ha.virtual-ip: "10.0.1.10/24" @@ -173,7 +173,7 @@ For clusters that do not have TiProxy deployed, you can enable TiProxy by scalin ```yaml component_versions: - tiproxy: "v1.3.2" + tiproxy: "v1.3.3" server_configs: tiproxy: ha.virtual-ip: "10.0.1.10/24" From f7f215f7734579eed477e460e1758aeee394b859 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sun, 20 Sep 2026 16:44:46 +0800 Subject: [PATCH 2/6] Apply suggestions from code review --- tiproxy/tiproxy-configuration.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index 2b7ee8d29701e..0eeedba2732f3 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -155,8 +155,6 @@ Configurations for the load balancing policy of TiProxy. + Possible values: `resource`, `location`, `connection` + Specifies the load balancing policy. For the meaning of each possible value, see [TiProxy load balancing policies](/tiproxy/tiproxy-load-balance.md#configure-load-balancing-policies). -<<<<<<< HEAD -======= #### `routing-policy` New in v1.3.3 + Default value: `prefer-idle` @@ -285,8 +283,6 @@ Configuration for connection-count-based load balancing. + Support hot-reload: yes + Possible values: `true`, `false` + Specifies whether to enable [traffic replay](/tiproxy/tiproxy-traffic-replay.md). If it is set to `false`, traffic capture and replay operations will result in errors. - ->>>>>>> f9f08f3606 (Update TiProxy to v1.3.3 (#23905)) ### ha High availability configurations for TiProxy. From d0c487af247cecac8dbb227d8d8300034b728bda Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sun, 20 Sep 2026 16:46:16 +0800 Subject: [PATCH 3/6] Update tiproxy/tiproxy-configuration.md --- tiproxy/tiproxy-configuration.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index 0eeedba2732f3..d6fc3f54efe9a 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -277,12 +277,6 @@ Configuration for connection-count-based load balancing. + Value range: `0` or `> 1` + Specifies the connection count ratio threshold for triggering connection-count-based migration. When the ratio of the backend with the most connections to the backend with the fewest connections exceeds this threshold, TiProxy starts migrating connections. Increasing this value can reduce migration frequency. -### `enable-traffic-replay` - -+ Default value: `true` -+ Support hot-reload: yes -+ Possible values: `true`, `false` -+ Specifies whether to enable [traffic replay](/tiproxy/tiproxy-traffic-replay.md). If it is set to `false`, traffic capture and replay operations will result in errors. ### ha High availability configurations for TiProxy. From 8785f53df8c289888d02cdc25d8d0ed2c82f0576 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Sun, 20 Sep 2026 17:30:23 +0800 Subject: [PATCH 4/6] Apply suggestions from code review --- tiproxy/tiproxy-configuration.md | 24 ++++++++++++------------ tiproxy/tiproxy-grafana.md | 2 +- tiproxy/tiproxy-load-balance.md | 4 ++-- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index d6fc3f54efe9a..4c88436667378 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -70,21 +70,21 @@ Configuration for SQL port. #### `fail-backend-list` New in v1.3.3 + Default value: `[]` -+ Hot-reload supported: Yes ++ Support hot-reload: yes + Specifies the list of backends to remove from routing. After confirming that a TiDB server has failed, you can add it to this list. TiProxy stops routing new connections to these backends and migrates existing connections away from them. Each item in the list can be in one of the following two forms: - Backend Pod name, for example, `"db-tidb-0"` - Backend address in the format of `:`, for example, `"10.0.0.10:4000"` -+ If applying this list would leave no routable backends, TiProxy ignores this list to ensure that requests can still be routed. ++ If applying this list would leave no routable backends, TiProxy ignores this list to ensure that connection requests can still be routed. #### `failover-timeout` New in v1.3.3 + Default value: `60` + Hot-reload supported: Yes -+ Unit: seconds ++ Unit: second + Range: `>= 0` -+ When a backend appears in [`fail-backend-list`](#fail-backend-list-new-in-v133), TiProxy migrates existing connections away from that backend. If there are still remaining connections on that backend after `failover-timeout` seconds, TiProxy forcibly closes these connections. `0` means to forcibly close the remaining connections immediately. ++ When a backend appears in [`fail-backend-list`](#fail-backend-list-new-in-v133), TiProxy migrates existing connections away from that backend. If any connections remain on that backend after `failover-timeout` seconds, TiProxy forcibly closes these connections. `0` means that TiProxy forcibly closes any remaining connections immediately. #### `max-connections` @@ -97,8 +97,8 @@ Configuration for SQL port. + Default value: `0.9` + Hot-reload supported: Yes + Range: `[0, 1]` -+ When TiProxy's memory usage reaches or exceeds this threshold, TiProxy rejects new connections, and the status port returns an unhealthy status. Existing connections are not affected. If [`ha.virtual-ip`](#virtual-ip) is configured, the instance also releases the virtual IP. For example, `0.9` means that it takes effect when memory usage reaches 90%. -+ `0` means not rejecting new connections due to memory usage. If the configured value is greater than `0` and less than `0.5`, TiProxy adjusts it to `0.5`. ++ When the memory usage of TiProxy reaches or exceeds this threshold, TiProxy rejects new connections, and the status port returns an unhealthy status. Existing connections are not affected. If [`ha.virtual-ip`](#virtual-ip) is configured, the instance also releases the virtual IP. For example, `0.9` means that TiProxy starts rejecting new connections when the memory usage reaches 90%. ++ `0` means that TiProxy does not reject new connections based on memory usage. If the configured value is greater than `0` and less than `0.5`, TiProxy adjusts it to `0.5`. #### `conn-buffer-size` @@ -163,7 +163,7 @@ Configurations for the load balancing policy of TiProxy. + Specifies the routing policy for new connections: - `prefer-idle`: Excludes backends that need connection migration, and then randomly selects from the remaining routable backends. Suitable for most scenarios. - - `random`: Randomly selects from routable backends, where the idlest backend has a slightly higher probability of being selected. Suitable for scenarios where new connections are created more intensively. + - `random`: Randomly selects from routable backends, where the idlest backend has a slightly higher probability of being selected. Suitable for scenarios with a high rate of new connections. - `idlest`: Always routes new connections to the idlest routable backend. Suitable for scenarios with long-lived connections and infrequent connection creation. #### `status` New in v1.3.3 @@ -226,7 +226,7 @@ Configuration for CPU-based load balancing. This item takes effect only when [`p + Default value: `0` + Hot-reload supported: Yes + Range: `>= 0` -+ Specifies the number of connections migrated per second for CPU-based load balancing. `0` indicates that TiProxy automatically calculates the migration rate. It is not recommended to set this value too high when CPU hotspots are unstable, to avoid repeated connection migrations. ++ Specifies the number of connections migrated per second for CPU-based load balancing. `0` indicates that TiProxy automatically calculates the migration rate. When CPU hotspots shift frequently, it is not recommended to set this value too high to avoid repeated connection migrations. ##### `min-balance-usage` New in v1.3.3 @@ -239,7 +239,7 @@ Configuration for CPU-based load balancing. This item takes effect only when [`p + Default value: `1` + Hot-reload supported: Yes -+ Value range: `0` or `[0.05, 1]` ++ Range: `0` or `[0.05, 1]` + Specifies the minimum CPU usage difference required to trigger CPU-based connection migration. Migration is triggered when the CPU usage difference between the source backend and the target backend reaches this threshold. For example, `0.1` means migration can be triggered when the difference reaches 10%. The default value `1` means whether to migrate depends only on adaptive rules. If you need more balanced CPU usage across backends, you can reduce this value appropriately. #### `location` New in v1.3.3 @@ -313,16 +313,16 @@ Starting from v1.3.1, TiProxy supports configuring multiple virtual IP addresses #### `garp-burst-count` New in v1.3.3 + Default value: `5` -+ Hot-reload supported: No ++ Support hot-reload: no + Value range: `>= 0` + Specifies the number of GARP (Gratuitous ARP) packets sent immediately after a TiProxy instance takes over and binds the virtual IP. GARP is used to notify switches and hosts to update the MAC address corresponding to the virtual IP, so that client traffic can be switched to the TiProxy instance that has taken over the virtual IP as soon as possible. Sending multiple packets continuously can reduce the risk of switchover delay caused by the loss of the first GARP packet. `0` is automatically adjusted to `1`. #### `garp-refresh-count` New in v1.3.3 + Default value: `30` -+ Hot-reload: No ++ Support hot-reload: no + Range: `>= 0` -+ Specifies the number of times to additionally send GARP after taking over the virtual IP. The interval between two sends is 1 second, and [`garp-burst-count`](#garp-burst-count-new-in-v133) packets are sent each time. This is used to refresh the previous virtual IP-to-MAC address mapping in upstream devices for a period of time after failover, to avoid traffic still being forwarded to the old instance. `0` means no additional packets are sent after takeover. ++ Specifies the number of times to additionally send GARP bursts after taking over the virtual IP. The interval between two sends is 1 second, and [`garp-burst-count`](#garp-burst-count-new-in-v133) packets are sent each time. This is used to refresh the previous virtual IP-to-MAC address mapping in upstream devices for a period of time after failover, to avoid traffic still being forwarded to the old instance. `0` means no additional packets are sent after takeover. ### `labels` diff --git a/tiproxy/tiproxy-grafana.md b/tiproxy/tiproxy-grafana.md index 0b08a15534b54..3b3d21d1fd8be 100644 --- a/tiproxy/tiproxy-grafana.md +++ b/tiproxy/tiproxy-grafana.md @@ -37,7 +37,7 @@ TiProxy has four panel groups. The metrics on these panels indicate the current - proxy error: other TiProxy errors - backend network break: fails to read from or write to the TiDB. This may be caused by a network problem or the TiDB server shutting down - backend handshake fail: TiProxy fails to handshake with the TiDB server -- Connection Lifetime: the average and P99 values of connection lifetime +- Connection Lifetime: the average and P99 connection lifetimes - Goroutine Count: the number of Goroutines on each TiProxy instance - Owner: the TiProxy instance that executes various tasks. For example, `10.24.31.1:3080 - vip` indicates that the TiProxy instance at `10.24.31.1:3080` is bound to a virtual IP. The tasks include the following: - vip: binds a virtual IP diff --git a/tiproxy/tiproxy-load-balance.md b/tiproxy/tiproxy-load-balance.md index 215e3f567018b..5f21499d87a23 100644 --- a/tiproxy/tiproxy-load-balance.md +++ b/tiproxy/tiproxy-load-balance.md @@ -12,7 +12,7 @@ By default, TiProxy applies these policies with the following priorities: 1. Label-based load balancing: TiProxy prioritizes routing connection requests to TiDB servers that share the same label as the TiProxy instance, enabling resource isolation at the computing layer. 2. Status-based load balancing: when a TiDB server cannot provide service normally or is shutting down, TiProxy migrates connections from that TiDB server to an online TiDB server. 3. Health-based load balancing: when the health of a TiDB server is abnormal, TiProxy migrates connections from that TiDB server to a healthy TiDB server. -4. Memory-based load balancing: when a TiDB server is at risk of Out of Memory (OOM), TiProxy migrates connections from that TiDB server to a TiDB server with lower memory usage. +4. Memory-based load balancing: when a TiDB server is at risk of running out of memory (OOM), TiProxy migrates connections from that TiDB server to a TiDB server with lower memory usage. 5. CPU-based load balancing: when the CPU usage of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with lower CPU usage. 6. Location-based load balancing: TiProxy prioritizes routing requests to TiDB servers that are geographically closer to TiProxy. 7. Connection count-based load balancing: when the connection count of a TiDB server is much higher than that of other TiDB servers, TiProxy migrates connections from that TiDB server to a TiDB server with fewer connections. @@ -98,7 +98,7 @@ pd_servers: ## Status-based load balancing -TiProxy periodically checks whether a TiDB server can provide services properly using the SQL port and status port, including whether it is offline or shutting down. +TiProxy periodically checks whether a TiDB server can provide services normally using the SQL port and status port, such as whether it is offline or shutting down. ## Health-based load balancing From 7bf78da816e5011c6ff3f1ec562deee0ae28897b Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 21 Sep 2026 09:19:58 +0800 Subject: [PATCH 5/6] Update TiProxy load balancing configuration --- tiproxy/tiproxy-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index 4c88436667378..33aec88fb2193 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -240,7 +240,7 @@ Configuration for CPU-based load balancing. This item takes effect only when [`p + Default value: `1` + Hot-reload supported: Yes + Range: `0` or `[0.05, 1]` -+ Specifies the minimum CPU usage difference required to trigger CPU-based connection migration. Migration is triggered when the CPU usage difference between the source backend and the target backend reaches this threshold. For example, `0.1` means migration can be triggered when the difference reaches 10%. The default value `1` means whether to migrate depends only on adaptive rules. If you need more balanced CPU usage across backends, you can reduce this value appropriately. ++ Specifies the minimum CPU usage difference required to trigger CPU-based connection migration. Migration is triggered when the CPU usage difference between the source backend and the target backend reaches this threshold. For example, `0.1` means migration can be triggered when the difference reaches 10%. The default value `1` means whether to migrate depends only on adaptive rules. `0` means this parameter uses the default value. If you need more balanced CPU usage across backends, you can reduce this value appropriately. #### `location` New in v1.3.3 @@ -257,7 +257,7 @@ Configuration for location-based load balancing. This item takes effect only whe + Default value: `0` + Hot-reload supported: Yes + Value range: `>= 0` -+ Specifies the number of connections migrated per second for location-based load balancing. `0` means the default migration rate is used (1 connection per second). ++ Specifies the number of connections migrated per second for location-based load balancing. `0` means the default migration rate is used. #### `conn-count` New in v1.3.3 @@ -275,7 +275,7 @@ Configuration for connection-count-based load balancing. + Default value: `1.2` + Hot-reload supported: Yes + Value range: `0` or `> 1` -+ Specifies the connection count ratio threshold for triggering connection-count-based migration. When the ratio of the backend with the most connections to the backend with the fewest connections exceeds this threshold, TiProxy starts migrating connections. Increasing this value can reduce migration frequency. ++ Specifies the connection count ratio threshold for triggering connection-count-based migration. When the ratio of the backend with the most connections to the backend with the fewest connections exceeds this threshold, TiProxy starts migrating connections. Increasing this value can reduce migration frequency. `0` means this parameter uses the default value. ### ha From 729037f60484a1c21d6413fb1b8ea0d5d088b9e5 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 21 Sep 2026 09:28:44 +0800 Subject: [PATCH 6/6] Update tiproxy-configuration.md --- tiproxy/tiproxy-configuration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tiproxy/tiproxy-configuration.md b/tiproxy/tiproxy-configuration.md index 33aec88fb2193..12c61e6820ea5 100644 --- a/tiproxy/tiproxy-configuration.md +++ b/tiproxy/tiproxy-configuration.md @@ -185,7 +185,7 @@ Health-based load balancing configuration. It takes effect only when [`policy`]( + Default value: `true` + Hot-reload supported: Yes -+ Whether to enable [health-based load balancing](/tiproxy/tiproxy-load-balance.md#health-based-load-balancing). ++ Controls whether to enable [health-based load balancing](/tiproxy/tiproxy-load-balance.md#health-based-load-balancing). ##### `migrations-per-second` New in v1.3.3 @@ -202,7 +202,7 @@ Configuration for memory-based load balancing. This item takes effect only when + Default value: `true` + Hot-reload supported: Yes -+ Whether to enable [memory-based load balancing](/tiproxy/tiproxy-load-balance.md#memory-based-load-balancing). ++ Controls whether to enable [memory-based load balancing](/tiproxy/tiproxy-load-balance.md#memory-based-load-balancing). ##### `migrations-per-second` New in v1.3.3 @@ -219,7 +219,7 @@ Configuration for CPU-based load balancing. This item takes effect only when [`p + Default value: `true` + Hot-reload supported: Yes -+ Whether to enable [CPU-based load balancing](/tiproxy/tiproxy-load-balance.md#cpu-based-load-balancing). ++ Controls whether to enable [CPU-based load balancing](/tiproxy/tiproxy-load-balance.md#cpu-based-load-balancing). ##### `migrations-per-second` New in v1.3.3 @@ -250,7 +250,7 @@ Configuration for location-based load balancing. This item takes effect only whe + Default value: `true` + Hot-reload supported: Yes -+ Whether to enable [location-based load balancing](/tiproxy/tiproxy-load-balance.md#location-based-load-balancing). ++ Controls whether to enable [location-based load balancing](/tiproxy/tiproxy-load-balance.md#location-based-load-balancing). ##### `migrations-per-second` New in v1.3.3