From 7ee0061f76e2f750a41e3d358440c44cf6c2c42f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 13 Feb 2026 17:39:36 +0800 Subject: [PATCH 1/5] Add temp.md --- temp.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 temp.md diff --git a/temp.md b/temp.md new file mode 100644 index 0000000000000..af27ff4986a7b --- /dev/null +++ b/temp.md @@ -0,0 +1 @@ +This is a test file. \ No newline at end of file From 604b658d04063070ba88928525fbbf22775bdd7d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 13 Feb 2026 17:39:41 +0800 Subject: [PATCH 2/5] Delete temp.md --- temp.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 temp.md diff --git a/temp.md b/temp.md deleted file mode 100644 index af27ff4986a7b..0000000000000 --- a/temp.md +++ /dev/null @@ -1 +0,0 @@ -This is a test file. \ No newline at end of file From 3b1b22a114b57464bdf71cc2a35623c1f9cdbcec Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 13 Feb 2026 09:41:07 +0000 Subject: [PATCH 3/5] Auto-sync: Update English docs from Chinese PR Synced from: https://github.com/pingcap/docs-cn/pull/21365 Target PR: https://github.com/pingcap/docs/pull/22464 AI Provider: gemini Co-authored-by: github-actions[bot] --- TOC-develop.md | 2 +- TOC.md | 1 + develop/dev-guide-delete-data.md | 4 +- develop/dev-guide-time-to-live.md | 69 +++++++++++++++++++++++++++++++ time-to-live.md | 4 +- 5 files changed, 75 insertions(+), 5 deletions(-) create mode 100644 develop/dev-guide-time-to-live.md diff --git a/TOC-develop.md b/TOC-develop.md index 9300837095adb..2666d25b2700b 100644 --- a/TOC-develop.md +++ b/TOC-develop.md @@ -67,7 +67,7 @@ - [Insert Data](/develop/dev-guide-insert-data.md) - [Update Data](/develop/dev-guide-update-data.md) - [Delete Data](/develop/dev-guide-delete-data.md) - - [Periodically Delete Expired Data Using TTL (Time to Live)](/time-to-live.md) + - [Periodically Delete Expired Data Using TTL (Time to Live)](/develop/dev-guide-time-to-live.md) - [Prepared Statements](/develop/dev-guide-prepared-statement.md) - Read Data - [Query Data from a Single Table](/develop/dev-guide-get-data-from-single-table.md) diff --git a/TOC.md b/TOC.md index a99065630e0d8..f1e69ac757588 100644 --- a/TOC.md +++ b/TOC.md @@ -873,6 +873,7 @@ - [Overview](/character-set-and-collation.md) - [GBK](/character-set-gbk.md) - [GB18030](/character-set-gb18030.md) + - [TTL (Time to Live)](/time-to-live.md) - [Placement Rules in SQL](/placement-rules-in-sql.md) - System Tables - `mysql` Schema diff --git a/develop/dev-guide-delete-data.md b/develop/dev-guide-delete-data.md index dc80098e0b3cd..95594e0b51974 100644 --- a/develop/dev-guide-delete-data.md +++ b/develop/dev-guide-delete-data.md @@ -1,12 +1,12 @@ --- title: Delete Data summary: Learn about the SQL syntax, best practices, and examples for deleting data. -aliases: ['/tidb/stable/dev-guide-delete-data/','/tidb/dev/dev-guide-delete-data/','/tidbcloud/dev-guide-delete-data/'] +aliases: ['/tidb/dev/delete-data','/tidb/stable/dev-guide-delete-data/','/tidb/dev/dev-guide-delete-data/','/tidbcloud/dev-guide-delete-data/'] --- # Delete Data -This document describes how to use the [DELETE](/sql-statements/sql-statement-delete.md) SQL statement to delete the data in TiDB. If you need to periodically delete expired data, use the [time to live](/time-to-live.md) feature. +This document describes how to use the [DELETE](/sql-statements/sql-statement-delete.md) SQL statement to delete the data in TiDB. If you need to periodically delete expired data, use the [time to live](/develop/dev-guide-time-to-live.md) feature. ## Before you start diff --git a/develop/dev-guide-time-to-live.md b/develop/dev-guide-time-to-live.md new file mode 100644 index 0000000000000..975a407cf9c4a --- /dev/null +++ b/develop/dev-guide-time-to-live.md @@ -0,0 +1,69 @@ +--- +title: Regularly Delete Expired Data Using TTL (Time to Live) +summary: Learn how to leverage TiDB's TTL feature to automatically and periodically delete expired data. +--- + +# Regularly Delete Expired Data Using TTL (Time to Live) + +In application development, some data is only valuable for a specific period. For example, verification codes typically only need to be kept for a few minutes, short links might only be valid during an event, and access logs or intermediate calculation results often only need to be stored for a few months. + +TiDB's [TTL (Time to Live)](/time-to-live.md) feature provides a row-level lifecycle control policy that helps you **automatically and periodically** delete this expired data without the need to write complex scheduled task scripts. + +## Applicable Scenarios + +TTL is designed to address the data cleanup problem of "data that no longer has business value after expiration" and is suitable for the following scenarios: + +- Periodically deleting verification codes and short URL records +- Periodically deleting unnecessary historical orders +- Automatically deleting intermediate calculation results + +> **Note:** +> +> TTL tasks are executed periodically in the background, so there is no guarantee that data will be deleted immediately after expiration. + +## Quick Start + +You can configure the TTL attribute directly when creating a table, or you can modify an existing table. The following sections list basic examples of using TTL to regularly delete expired data. For complete examples, TTL usage limitations, and TTL compatibility with other tools or features, please refer to [TTL (Time to Live)](/time-to-live.md). + +### Creating a Table with TTL + +To create a table `app_messages` for storing instant messages, and you want messages to be automatically deleted 3 months after creation, you can execute the following statement: + +```sql +CREATE TABLE app_messages ( + id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY, + sender_id INT, + msg_content TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +) TTL = `created_at` + INTERVAL 3 MONTH; +``` + +Here, `TTL = ...` is used to define the expiration policy, `created_at` represents the creation time of the data, and `INTERVAL 3 MONTH` sets the maximum survival time of rows in the table to 3 months. + +### Adding TTL to an Existing Table + +If you already have a table named `app_logs` and need to add automatic cleanup functionality to it (e.g., keeping data for only 1 month), you can execute the following statement: + +```sql +ALTER TABLE app_logs TTL = `created_at` + INTERVAL 1 MONTH; +``` + +### Adjusting the TTL Duration + +To adjust the TTL duration for the table `app_logs`, you can execute the following statement: + +```sql +ALTER TABLE app_logs TTL = `created_at` + INTERVAL 6 MONTH; +``` + +### Disabling the TTL Feature + +To disable the TTL feature for the table `app_logs`, you can execute the following statement: + +```sql +ALTER TABLE app_logs TTL_ENABLE = 'OFF'; +``` + +## See Also + +- [TTL (Time to Live)](/time-to-live.md) \ No newline at end of file diff --git a/time-to-live.md b/time-to-live.md index 146d4177fa46f..05c60079086eb 100644 --- a/time-to-live.md +++ b/time-to-live.md @@ -1,9 +1,9 @@ --- -title: Periodically Delete Data Using TTL (Time to Live) +title: TTL (Time to Live) summary: Time to live (TTL) is a feature that allows you to manage TiDB data lifetime at the row level. In this document, you can learn how to use TTL to automatically expire and delete old data. --- -# Periodically Delete Expired Data Using TTL (Time to Live) +# TTL (Time to Live) Time to live (TTL) is a feature that allows you to manage TiDB data lifetime at the row level. For a table with the TTL attribute, TiDB automatically checks data lifetime and deletes expired data at the row level. This feature can effectively save storage space and enhance performance in some scenarios. From e940d7ca04a0e6ce7fd075bcd171c15f0b750001 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 13 Feb 2026 17:44:03 +0800 Subject: [PATCH 4/5] Update develop/dev-guide-delete-data.md --- develop/dev-guide-delete-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop/dev-guide-delete-data.md b/develop/dev-guide-delete-data.md index 95594e0b51974..ca695370ffede 100644 --- a/develop/dev-guide-delete-data.md +++ b/develop/dev-guide-delete-data.md @@ -1,7 +1,7 @@ --- title: Delete Data summary: Learn about the SQL syntax, best practices, and examples for deleting data. -aliases: ['/tidb/dev/delete-data','/tidb/stable/dev-guide-delete-data/','/tidb/dev/dev-guide-delete-data/','/tidbcloud/dev-guide-delete-data/'] +aliases: ['/tidb/stable/dev-guide-delete-data/','/tidb/dev/dev-guide-delete-data/','/tidbcloud/dev-guide-delete-data/'] --- # Delete Data From 49d9971fe88b3f32ace564a43f26fdbb68485f5e Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 13 Feb 2026 18:09:35 +0800 Subject: [PATCH 5/5] Update dev-guide-time-to-live.md --- develop/dev-guide-time-to-live.md | 44 +++++++++++++++---------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/develop/dev-guide-time-to-live.md b/develop/dev-guide-time-to-live.md index 975a407cf9c4a..d3b45d48b765b 100644 --- a/develop/dev-guide-time-to-live.md +++ b/develop/dev-guide-time-to-live.md @@ -1,33 +1,33 @@ --- -title: Regularly Delete Expired Data Using TTL (Time to Live) -summary: Learn how to leverage TiDB's TTL feature to automatically and periodically delete expired data. +title: Periodically Delete Data Using TTL (Time to Live) +summary: Learn how to use the TTL feature of TiDB to automatically and periodically delete expired data. --- -# Regularly Delete Expired Data Using TTL (Time to Live) +# Periodically Delete Data Using TTL (Time to Live) -In application development, some data is only valuable for a specific period. For example, verification codes typically only need to be kept for a few minutes, short links might only be valid during an event, and access logs or intermediate calculation results often only need to be stored for a few months. +In application development, some data is only valuable for a limited period of time. For example, verification codes typically need to be retained for only a few minutes, short links might be valid only during a specific campaign, and access logs or intermediate computation results are often kept for just a few months. -TiDB's [TTL (Time to Live)](/time-to-live.md) feature provides a row-level lifecycle control policy that helps you **automatically and periodically** delete this expired data without the need to write complex scheduled task scripts. +TiDB provides the [TTL (Time to Live)](/time-to-live.md) feature, which helps you manage the lifetime of TiDB data at the row level. With TTL, you can **automatically and periodically** remove expired data without writing complex scheduled cleanup scripts. -## Applicable Scenarios +## Use cases -TTL is designed to address the data cleanup problem of "data that no longer has business value after expiration" and is suitable for the following scenarios: +TTL is designed for scenarios where data no longer has business value after a certain period of time. Typical use cases include the following: - Periodically deleting verification codes and short URL records -- Periodically deleting unnecessary historical orders -- Automatically deleting intermediate calculation results +- Periodically cleaning up outdated historical orders +- Automatically removing intermediate computation results > **Note:** > -> TTL tasks are executed periodically in the background, so there is no guarantee that data will be deleted immediately after expiration. +> TTL jobs run periodically in the background. Therefore, expired data is not guaranteed to be deleted immediately after it reaches its expiration time. -## Quick Start +## Quick start -You can configure the TTL attribute directly when creating a table, or you can modify an existing table. The following sections list basic examples of using TTL to regularly delete expired data. For complete examples, TTL usage limitations, and TTL compatibility with other tools or features, please refer to [TTL (Time to Live)](/time-to-live.md). +You can configure the TTL attribute when creating a table, or add it to an existing table. The following sections provide basic examples of how to use TTL to periodically delete expired data. For complete examples, usage restrictions, and compatibility details with other tools or features, see [TTL (Time to Live)](/time-to-live.md). -### Creating a Table with TTL +### Create a table with TTL -To create a table `app_messages` for storing instant messages, and you want messages to be automatically deleted 3 months after creation, you can execute the following statement: +To create a table named `app_messages` for storing instant messages and automatically delete messages three months after their creation, execute the following statement: ```sql CREATE TABLE app_messages ( @@ -38,32 +38,32 @@ CREATE TABLE app_messages ( ) TTL = `created_at` + INTERVAL 3 MONTH; ``` -Here, `TTL = ...` is used to define the expiration policy, `created_at` represents the creation time of the data, and `INTERVAL 3 MONTH` sets the maximum survival time of rows in the table to 3 months. +In this example, `TTL = ...` defines the expiration policy. The `created_at` column records the creation time of each row, and `INTERVAL 3 MONTH` specifies that each row is retained for a maximum of three months. -### Adding TTL to an Existing Table +### Configure the TTL attribute for an existing table -If you already have a table named `app_logs` and need to add automatic cleanup functionality to it (e.g., keeping data for only 1 month), you can execute the following statement: +If you already have a table named `app_logs` and want to enable automatic cleanup (for example, retaining only one month of data), execute the following statement: ```sql ALTER TABLE app_logs TTL = `created_at` + INTERVAL 1 MONTH; ``` -### Adjusting the TTL Duration +### Modify the TTL period -To adjust the TTL duration for the table `app_logs`, you can execute the following statement: +To modify the retention period for the `app_logs` table, execute the following statement: ```sql ALTER TABLE app_logs TTL = `created_at` + INTERVAL 6 MONTH; ``` -### Disabling the TTL Feature +### Disable TTL -To disable the TTL feature for the table `app_logs`, you can execute the following statement: +To disable TTL for the `app_logs` table, execute the following statement: ```sql ALTER TABLE app_logs TTL_ENABLE = 'OFF'; ``` -## See Also +## See also - [TTL (Time to Live)](/time-to-live.md) \ No newline at end of file