Skip to content

cloud: add maximum lifetime of connections #21895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Parent: cloud: add public/TLS connection docs for premium
wants to merge 7 commits into
base: release-8.5
Choose a base branch
from
+34 −1
Open

cloud: add maximum lifetime of connections #21895

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
428018f
Add connection lifetime limitation
sunxiaoguang Oct 24, 2025
571a170
Update recommended lifetime
sunxiaoguang Oct 24, 2025
dd660dc
Apply suggestion from @gemini-code-assist[bot]
likidu Oct 24, 2025
8736ebf
Apply suggestion from @gemini-code-assist[bot]
likidu Oct 24, 2025
0229051
Fix
sunxiaoguang Oct 24, 2025
17d8c7e
Update develop/dev-guide-connection-parameters.md
sunxiaoguang Oct 27, 2025
da66410
Update tidb-cloud/serverless-limitations.md
sunxiaoguang Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 33 additions & 1 deletion develop/dev-guide-connection-parameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,38 @@ 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 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:

<SimpleTab>
<div label="HikariCP">

- **maxLifetime**: The maximum lifetime of a connection in the pool.

</div>

<div label="tomcat-jdbc">

- **maxAge**: The maximum lifetime of a connection in the pool.

</div>

<div label="c3p0">

- **maxConnectionAge**: The maximum lifetime of a connection in the pool.

</div>

<div label="dbcp">

- **maxConnLifetimeMillis**: The maximum lifetime of a connection in the pool.
Comment on lines +46 to +64
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **maxLifetime**: The maximum lifetime of a connection in the pool.
</div>
<div label="tomcat-jdbc">
- **maxAge**: The maximum lifetime of a connection in the pool.
</div>
<div label="c3p0">
- **maxConnectionAge**: The maximum lifetime of a connection in the pool.
</div>
<div label="dbcp">
- **maxConnLifetimeMillis**: The maximum lifetime of a connection in the pool.
- **`maxLifetime`**: The maximum lifetime of a connection in the pool.
</div>
<div label="tomcat-jdbc">
- **`maxAge`**: The maximum lifetime of a connection in the pool.
</div>
<div label="c3p0">
- **`maxConnectionAge`**: The maximum lifetime of a connection in the pool.
</div>
<div label="dbcp">
- **`maxConnLifetimeMillis`**: The maximum lifetime of a connection in the pool.


</div>
</SimpleTab>

### Probe configuration

The connection pool maintains persistent connections from clients to TiDB as follows:
Expand Down Expand Up @@ -293,4 +325,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/).

</CustomContent>
</CustomContent>
1 change: 1 addition & 0 deletions tidb-cloud/serverless-limitations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
- 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:**
>
Expand Down
Loading