From 428018fa14ea0b5977f21da58ed1e4ff80c5d6f4 Mon Sep 17 00:00:00 2001 From: Xiaoguang Sun Date: Fri, 24 Oct 2025 19:27:20 +0800 Subject: [PATCH 1/8] Add connection lifetime limitation --- develop/dev-guide-connection-parameters.md | 32 +++++++++++++++++++++- tidb-cloud/serverless-limitations.md | 1 + 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index b4ef34c17399f..2c4bfc435241b 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -34,6 +34,36 @@ It is a common practice that the connection pool size is well adjusted according The application needs to return the connection after finishing using it. It is recommended that the application uses the corresponding connection pool monitoring (such as **metricRegistry**) to locate connection pool issues in time. +### Configure the lifetime of connections + +When a TiDB server is shut down or restarted for maintenance or due to hardware failure, client connections may be reset, leading to application disruptions. It is recommended to close and reconnect long-running database connections at least once a day. + + +
+ +- **maxLifetime**: The maximum lifetime of a connection in the pool. + +
+ +
+ +- **maxAge**: The maximum lifetime of a connection in the pool. + +
+ +
+ +- **maxConnectionAge**: The maximum lifetime of a connection in the pool. + +
+ +
+ +- **maxConnLifetimeMillis**: The maximum lifetime of a connection in the pool. + +
+ + ### Probe configuration The connection pool maintains persistent connections from clients to TiDB as follows: @@ -293,4 +323,4 @@ Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or Ask the community on [Discord](https://discord.gg/DQZ2dy3cuc?utm_source=doc) or [Slack](https://slack.tidb.io/invite?team=tidb-community&channel=everyone&ref=pingcap-docs), or [submit a support ticket](https://tidb.support.pingcap.com/). - \ No newline at end of file + diff --git a/tidb-cloud/serverless-limitations.md b/tidb-cloud/serverless-limitations.md index b8a31b5838202..f9c1d49f4101d 100644 --- a/tidb-cloud/serverless-limitations.md +++ b/tidb-cloud/serverless-limitations.md @@ -22,6 +22,7 @@ We are constantly filling in the feature gaps between {{{ .starter }}}/Essential - Only [Public Endpoint](/tidb-cloud/connect-via-standard-connection-serverless.md) and [Private Endpoint](/tidb-cloud/set-up-private-endpoint-connections-serverless.md) can be used. You cannot use [VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md) to connect to {{{ .starter }}} or {{{ .essential }}} clusters. - No [Firewall Rules](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md) support for Private Endpoint. +- Database client connections that remain open for more than 30 minutes may be terminated unexpectedly. When a server is shut down or restarted, client connections can be reset after this duration, resulting in application disruptions. It is recommended to start with a maximum connection lifetime of 15 minutes and extend it if you notice a negative impact on tail latency. Refer to the [recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters) for additional information. > **Note:** > From 571a1707cb94bc148ea9be9cc2f29079c58d2673 Mon Sep 17 00:00:00 2001 From: Xiaoguang Sun Date: Fri, 24 Oct 2025 19:29:27 +0800 Subject: [PATCH 2/8] Update recommended lifetime Signed-off-by: Xiaoguang Sun --- tidb-cloud/serverless-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-limitations.md b/tidb-cloud/serverless-limitations.md index f9c1d49f4101d..b1bff09f9b8d5 100644 --- a/tidb-cloud/serverless-limitations.md +++ b/tidb-cloud/serverless-limitations.md @@ -22,7 +22,7 @@ We are constantly filling in the feature gaps between {{{ .starter }}}/Essential - Only [Public Endpoint](/tidb-cloud/connect-via-standard-connection-serverless.md) and [Private Endpoint](/tidb-cloud/set-up-private-endpoint-connections-serverless.md) can be used. You cannot use [VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md) to connect to {{{ .starter }}} or {{{ .essential }}} clusters. - No [Firewall Rules](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md) support for Private Endpoint. -- Database client connections that remain open for more than 30 minutes may be terminated unexpectedly. When a server is shut down or restarted, client connections can be reset after this duration, resulting in application disruptions. It is recommended to start with a maximum connection lifetime of 15 minutes and extend it if you notice a negative impact on tail latency. Refer to the [recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters) for additional information. +- Database client connections that remain open for more than 30 minutes may be terminated unexpectedly. When a server is shut down or restarted, client connections can be reset after this duration, resulting in application disruptions. It is recommended to start with a maximum connection lifetime of 5 minutes and extend it if you notice a negative impact on tail latency. Refer to the [recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters) for additional information. > **Note:** > From dd660dce9ffaeebe7716914535c0b1be86e24b9c Mon Sep 17 00:00:00 2001 From: Liki Du Date: Fri, 24 Oct 2025 19:56:45 +0800 Subject: [PATCH 3/8] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- develop/dev-guide-connection-parameters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index 2c4bfc435241b..053d316003463 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -36,7 +36,7 @@ The application needs to return the connection after finishing using it. It is r ### Configure the lifetime of connections -When a TiDB server is shut down or restarted for maintenance or due to hardware failure, client connections may be reset, leading to application disruptions. It is recommended to close and reconnect long-running database connections at least once a day. +When a TiDB server shuts down or restarts for maintenance or due to a hardware failure, your client connections might be reset, which can lead to application disruptions. To avoid this, you should close and reconnect long-running database connections at least once a day.
From 8736ebfbf1ef9dd2985be3d92b74963ef3018ef1 Mon Sep 17 00:00:00 2001 From: Liki Du Date: Fri, 24 Oct 2025 19:57:08 +0800 Subject: [PATCH 4/8] Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tidb-cloud/serverless-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-limitations.md b/tidb-cloud/serverless-limitations.md index b1bff09f9b8d5..4b634bbacee8c 100644 --- a/tidb-cloud/serverless-limitations.md +++ b/tidb-cloud/serverless-limitations.md @@ -22,7 +22,7 @@ We are constantly filling in the feature gaps between {{{ .starter }}}/Essential - Only [Public Endpoint](/tidb-cloud/connect-via-standard-connection-serverless.md) and [Private Endpoint](/tidb-cloud/set-up-private-endpoint-connections-serverless.md) can be used. You cannot use [VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md) to connect to {{{ .starter }}} or {{{ .essential }}} clusters. - No [Firewall Rules](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md) support for Private Endpoint. -- Database client connections that remain open for more than 30 minutes may be terminated unexpectedly. When a server is shut down or restarted, client connections can be reset after this duration, resulting in application disruptions. It is recommended to start with a maximum connection lifetime of 5 minutes and extend it if you notice a negative impact on tail latency. Refer to the [recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters) for additional information. +- Your database client connections might be terminated unexpectedly if they remain open for more than 30 minutes. This can happen when a server shuts down or restarts, leading to application disruptions. To prevent this, you should configure a maximum connection lifetime. We recommend starting with 5 minutes and increasing it if you do not see a negative impact on tail latency. For more details, see [Recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters). > **Note:** > From 02290514d23a9991b66290cdc02768c3b22a24bd Mon Sep 17 00:00:00 2001 From: Xiaoguang Sun Date: Fri, 24 Oct 2025 22:19:31 +0800 Subject: [PATCH 5/8] Fix Signed-off-by: Xiaoguang Sun --- tidb-cloud/serverless-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-limitations.md b/tidb-cloud/serverless-limitations.md index 4b634bbacee8c..f7b32dd22b11d 100644 --- a/tidb-cloud/serverless-limitations.md +++ b/tidb-cloud/serverless-limitations.md @@ -22,7 +22,7 @@ We are constantly filling in the feature gaps between {{{ .starter }}}/Essential - Only [Public Endpoint](/tidb-cloud/connect-via-standard-connection-serverless.md) and [Private Endpoint](/tidb-cloud/set-up-private-endpoint-connections-serverless.md) can be used. You cannot use [VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md) to connect to {{{ .starter }}} or {{{ .essential }}} clusters. - No [Firewall Rules](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md) support for Private Endpoint. -- Your database client connections might be terminated unexpectedly if they remain open for more than 30 minutes. This can happen when a server shuts down or restarts, leading to application disruptions. To prevent this, you should configure a maximum connection lifetime. We recommend starting with 5 minutes and increasing it if you do not see a negative impact on tail latency. For more details, see [Recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters). +- Your database client connections might be terminated unexpectedly if they remain open for more than 30 minutes. This can happen when a server shuts down or restarts, leading to application disruptions. To prevent this, you should configure a maximum connection lifetime. We recommend starting with 5 minutes and increasing it if there is an impact on tail latency. For more details, see [Recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters). > **Note:** > From 17d8c7e53879634416d8633e1f7c81cce9013703 Mon Sep 17 00:00:00 2001 From: Xiaoguang Sun Date: Mon, 27 Oct 2025 16:18:28 +0800 Subject: [PATCH 6/8] Update develop/dev-guide-connection-parameters.md Co-authored-by: Grace Cai --- develop/dev-guide-connection-parameters.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index 053d316003463..469f0006cf64b 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -36,7 +36,9 @@ The application needs to return the connection after finishing using it. It is r ### Configure the lifetime of connections -When a TiDB server shuts down or restarts for maintenance or due to a hardware failure, your client connections might be reset, which can lead to application disruptions. To avoid this, you should close and reconnect long-running database connections at least once a day. +When a TiDB server shuts down, restarts for maintenance, or encounters unexpected issues such as hardware or network failures, your existing client connections might be reset, which can lead to application disruptions. To avoid such issues, it is recommended to close and recreate long-running database connections at least once a day. + +Most connection pool libraries provide a parameter to control the maximum lifetime of a connection:
From da664101c8e9b320902734bf03c7ad015d4cfa01 Mon Sep 17 00:00:00 2001 From: Xiaoguang Sun Date: Mon, 27 Oct 2025 16:19:05 +0800 Subject: [PATCH 7/8] Update tidb-cloud/serverless-limitations.md Co-authored-by: Grace Cai --- tidb-cloud/serverless-limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tidb-cloud/serverless-limitations.md b/tidb-cloud/serverless-limitations.md index f7b32dd22b11d..82493cf39f02e 100644 --- a/tidb-cloud/serverless-limitations.md +++ b/tidb-cloud/serverless-limitations.md @@ -22,7 +22,7 @@ We are constantly filling in the feature gaps between {{{ .starter }}}/Essential - Only [Public Endpoint](/tidb-cloud/connect-via-standard-connection-serverless.md) and [Private Endpoint](/tidb-cloud/set-up-private-endpoint-connections-serverless.md) can be used. You cannot use [VPC Peering](/tidb-cloud/set-up-vpc-peering-connections.md) to connect to {{{ .starter }}} or {{{ .essential }}} clusters. - No [Firewall Rules](/tidb-cloud/configure-serverless-firewall-rules-for-public-endpoints.md) support for Private Endpoint. -- Your database client connections might be terminated unexpectedly if they remain open for more than 30 minutes. This can happen when a server shuts down or restarts, leading to application disruptions. To prevent this, you should configure a maximum connection lifetime. We recommend starting with 5 minutes and increasing it if there is an impact on tail latency. For more details, see [Recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters). +- Your database client connections might be terminated unexpectedly if they remain open for more than 30 minutes. This can occur when a TiDB server shuts down, restarts, or undergoes maintenance, potentially causing application disruptions. To avoid this issue, configure a maximum connection lifetime. It is recommended to start with 5 minutes and increase it gradually if it affects tail latency. For more information, see [Recommended settings for connection pools](/develop/dev-guide-connection-parameters.md#connection-pools-and-connection-parameters). > **Note:** > From c587513a70a364dd09b3b771fc4ce1852ed6b547 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Tue, 28 Oct 2025 08:44:00 +0800 Subject: [PATCH 8/8] Update develop/dev-guide-connection-parameters.md Co-authored-by: Aolin --- develop/dev-guide-connection-parameters.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop/dev-guide-connection-parameters.md b/develop/dev-guide-connection-parameters.md index 469f0006cf64b..38a92ad92b190 100644 --- a/develop/dev-guide-connection-parameters.md +++ b/develop/dev-guide-connection-parameters.md @@ -43,25 +43,25 @@ Most connection pool libraries provide a parameter to control the maximum lifeti
-- **maxLifetime**: The maximum lifetime of a connection in the pool. +- **`maxLifetime`**: The maximum lifetime of a connection in the pool.
-- **maxAge**: The maximum lifetime of a connection in the pool. +- **`maxAge`**: The maximum lifetime of a connection in the pool.
-- **maxConnectionAge**: The maximum lifetime of a connection in the pool. +- **`maxConnectionAge`**: The maximum lifetime of a connection in the pool.
-- **maxConnLifetimeMillis**: The maximum lifetime of a connection in the pool. +- **`maxConnLifetimeMillis`**: The maximum lifetime of a connection in the pool.