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 b1c0d8ccb7ddf..72ba1c862e00f 100644 --- a/TOC.md +++ b/TOC.md @@ -868,6 +868,7 @@ - Character Set and Collation - [Overview](/character-set-and-collation.md) - [GBK](/character-set-gbk.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..ca695370ffede 100644 --- a/develop/dev-guide-delete-data.md +++ b/develop/dev-guide-delete-data.md @@ -6,7 +6,7 @@ aliases: ['/tidb/stable/dev-guide-delete-data/','/tidb/dev/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..d3b45d48b765b --- /dev/null +++ b/develop/dev-guide-time-to-live.md @@ -0,0 +1,69 @@ +--- +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. +--- + +# Periodically Delete Data Using TTL (Time to Live) + +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 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. + +## Use cases + +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 cleaning up outdated historical orders +- Automatically removing intermediate computation results + +> **Note:** +> +> 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 + +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). + +### Create a table with TTL + +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 ( + 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; +``` + +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. + +### Configure the TTL attribute for an existing table + +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; +``` + +### Modify the TTL period + +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; +``` + +### Disable TTL + +To disable TTL for the `app_logs` table, 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 6cebaa11b770e..568a84716b70e 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.