TDSQL Boundless TTL (Time to Liv

概述
TTL（Time To Live，数据生命周期管理）是 TDSQL Boundless 提供的行级过期数据自动清理能力。您可以在表上声明一个时间列和一段有效期，数据库会在后台自动识别并清理超过有效期的数据，无需应用层编写定时删除任务。
TTL 适用于日志、监控指标、订单流水等有明确保留期限的业务数据，帮助您控制数据规模、降低存储成本，同时避免手动执行大批量 DELETE 对业务造成的锁等待和性能抖动。
除直接删除过期数据外，TTL 还支持在删除前将数据归档到另一张表，满足既要清理热表又要保留历史数据的场景。
支持版本
适用于 TDSQL Boundless V21.6.4.0 及以上版本。
工作原理
声明 TTL 规则
TTL 规则在建表或修改表时声明，包含一个时间列和一段有效期，数据库会持续判断每行数据的 TTL 列取值是否早于"当前时间 - 有效期"，命中的行即视为过期数据，由后台任务批量清理。
CREATE TABLE t1 (
    id BIGINT PRIMARY KEY,
    created_at DATETIME NOT NULL,
    content VARCHAR(255)
) TTL = created_at + INTERVAL 30 DAY;
调度与执行
TTL 后台任务分为调度器和执行器两个角色，均运行在 SQLEngine 各节点上：
调度器：集群中仅有一个节点被选为 Leader（通过分布式锁选举），Leader 定期扫描已开启 TTL 的表，为其生成待执行的删除任务；同时负责将已结束的任务归档到历史记录，并清理超出调度时间窗口的待执行任务。
执行器：各节点的执行进程认领任务并分批删除过期数据，通过心跳机制维持任务归属，长时间无心跳的任务可被其他节点重新认领，避免单点故障导致任务卡死。
调度时间窗口
删除任务只在配置的时间窗口内执行，窗口外新任务不会被调度，进行中的任务不受影响。默认时间窗口为全天（00:00 至 23:59），可按需调整到业务低峰时段，减少对在线业务的影响。
归档后删除
除了直接删除过期数据外，TTL 还支持在删除前将数据归档到另一张表，满足既要清理热表又要保留历史数据的场景；为表配置归档表后，TTL 会强制采用 archive_then_delete 策略：每批过期数据先写入归档表，再从源表删除，两个操作在同一个事务内完成，避免数据丢失。
归档表需要与源表满足以下兼容性要求，声明时与任务执行时均会校验：
归档表必须已存在，且不能与源表是同一张表。
源表必须存在主键，隐藏主键（无显式主键）不支持配置归档表。
归档表的列必须是源表列的超集：源表的每个列，归档表中都要有同名列，且数据类型、字符集、是否可为空、默认值、生成列表达式均需与源表严格一致。归档表允许比源表多出额外的列。
如果 TTL 归档任务执行时和归档表中已存在的数据发生主键/唯一键冲突时，TDSQL Boundless 支持用 TTL_ARCHIVE_ON_CONFLICT 声明归档写入撞上归档表主键/唯一键时的处理方式；具体语法如下：
取值
含义
额外说明
STOP（默认）
归档时使用 INSERT INTO 语句，遇到主键/唯一键冲突时停止 TTL 任务；需要人工介入检查并且解决冲突后方可继续 TTL 任务
合规/审计、append-only 归档、不能改写历史
REPLACE
归档时使用 REPLACE INTO 语句，冲突时用当前过期源行覆盖归档表中的冲突行
会删除/覆盖归档表中的存量数据，需要谨慎使用
-- 建表时一并指定
CREATE TABLE orders (...)
  TTL = created_at + INTERVAL 6 MONTH
  TTL_ARCHIVE_TABLE = 'orders_history'
  TTL_ARCHIVE_ON_CONFLICT = 'STOP';   -- 或 'REPLACE'
 
-- ALTER table指定
ALTER TABLE orders TTL_ARCHIVE_ON_CONFLICT = 'REPLACE';
ALTER TABLE orders TTL_ARCHIVE_ON_CONFLICT = 'STOP';
使用限制
TTL 功能默认关闭，需要开启参数 ttl_enable 后台任务才会运行；关闭状态下，CREATE/ALTER TABLE 声明 TTL 规则不受影响，仅不会产生自动删除任务。
TTL 列仅支持 DATE、DATETIME、TIMESTAMP 类型（含精度变体），且该列必须为 NOT NULL，不能是 AUTO_INCREMENT 列。
临时表不支持声明 TTL 规则。
CREATE TABLE ... LIKE 不会继承源表的 TTL 相关属性（TTL 规则、TTL_ENABLE、TTL_JOB_INTERVAL、TTL_ARCHIVE_TABLE），需要在新表上重新声明。
配置归档表（TTL_ARCHIVE_TABLE）要求源表存在显式主键，隐藏主键的表不支持配置归档表。
TTL_ARCHIVE_ON_CONFLICT 配置为 REPLACE 会删除并覆盖归档表中的存量数据，需要在确认符合业务要求的情况下谨慎使用。
TTL 相关的 DDL 语句会通过 CDC 同步给下游，在执行 TTL 相关的 DDL 语句时，需要保证灾备 /binlog 的下游消费实例也支持对应的 TTL 语法。
TTL 任务触发的 DML 会通过 CDC 同步给下游，为了避免下游节点重复删除/归档，下游节点需要关闭 ttl_enable 变量。
使用说明
创建带 TTL 属性的表
在 CREATE TABLE 语句末尾追加 TTL 子句，指定时间列与有效期：
CREATE TABLE t_log (
    id BIGINT PRIMARY KEY,
    log_time DATETIME NOT NULL,
    content VARCHAR(255)
) TTL = log_time + INTERVAL 7 DAY;
支持的有效期单位包括 YEAR、MONTH、WEEK、DAY、HOUR、MINUTE。
可选择同时指定 TTL 任务的调度间隔，以及归档表：
CREATE TABLE t_log (
    id BIGINT PRIMARY KEY,
    log_time DATETIME NOT NULL,
    content VARCHAR(255)
) TTL = log_time + INTERVAL 7 DAY
  TTL_JOB_INTERVAL = '1h'
  TTL_ARCHIVE_TABLE = 'archive_db.t_log_archive';
修改与移除 TTL 规则
已有表可以通过 ALTER TABLE 添加、修改或移除 TTL 规则：
-- 为已有表添加或修改 TTL 规则
ALTER TABLE t_log TTL = log_time + INTERVAL 30 DAY;
﻿
-- 临时停用 TTL（保留规则定义，不产生新的删除任务）
ALTER TABLE t_log TTL_ENABLE = 'OFF';
﻿
-- 移除 TTL 规则
ALTER TABLE t_log REMOVE TTL;
配置归档表
为已有表绑定或解绑归档表：
-- 绑定归档表
ALTER TABLE t_log TTL_ARCHIVE_TABLE = 'archive_db.t_log_archive';
﻿
-- 解绑归档表，回退为直接删除
ALTER TABLE t_log TTL_ARCHIVE_TABLE = '';
查看 TTL 配置与任务
已开启 TTL 的表及其规则详情，可通过 INFORMATION_SCHEMA.TTL_TABLES 视图查询。
正在执行和等待中的删除任务，可通过 SYS.TTL_TASK 查询。
已结束的历史任务，可通过 SYS.TTL_TASK_HISTORY 查询。
相关参数
参数名
作用域
默认值
取值范围
说明
ttl_enable
GLOBAL
OFF
ON、OFF
TTL 后台任务的全局开关。关闭时所有 TTL 后台任务停止运行。
ttl_running_tasks
GLOBAL
1
0 - 256
单节点允许同时运行的 TTL 删除任务数上限。
ttl_delete_batch_size
GLOBAL
1000
1 - 1000000
每批删除的最大行数。
ttl_batch_interval
GLOBAL
100
0 - 60000
相邻两批删除之间的休眠时间，单位为毫秒，取值为0表示不休眠。
ttl_job_schedule_window_start_time
GLOBAL
00:00 +0:00
-
TTL 后台任务允许执行的时间窗口起始时间。
ttl_job_schedule_window_end_time
GLOBAL
23:59 +0:00
-
TTL 后台任务允许执行的时间窗口结束时间。
ttl_delete_strategy
GLOBAL
auto
auto、single_statement、scan_then_delete
手动指定删除策略；取值为 auto 时由内核根据 TTL 列索引情况自动选择。已配置归档表的表始终使用 archive_then_delete 策略，不受该参数影响。
ttl_archive_strict_row_match
GLOBAL
ON
ON、OFF
使用归档策略时，是否严格校验每批归档与删除的行数一致。

TTL (Time to Live)

本页目录：

概述

支持版本

工作原理

声明 TTL 规则

调度与执行

调度时间窗口

归档后删除

使用限制

使用说明

创建带 TTL 属性的表

修改与移除 TTL 规则

配置归档表

查看 TTL 配置与任务

相关参数

取值	含义	额外说明
STOP（默认）	归档时使用 INSERT INTO 语句，遇到主键/唯一键冲突时停止 TTL 任务；需要人工介入检查并且解决冲突后方可继续 TTL 任务	合规/审计、append-only 归档、不能改写历史
REPLACE	归档时使用 REPLACE INTO 语句，冲突时用当前过期源行覆盖归档表中的冲突行	会删除/覆盖归档表中的存量数据，需要谨慎使用

参数名	作用域	默认值	取值范围	说明
`ttl_enable`	GLOBAL	OFF	ON、OFF	TTL 后台任务的全局开关。关闭时所有 TTL 后台任务停止运行。
`ttl_running_tasks`	GLOBAL	1	0 - 256	单节点允许同时运行的 TTL 删除任务数上限。
`ttl_delete_batch_size`	GLOBAL	1000	1 - 1000000	每批删除的最大行数。
`ttl_batch_interval`	GLOBAL	100	0 - 60000	相邻两批删除之间的休眠时间，单位为毫秒，取值为`0`表示不休眠。
`ttl_job_schedule_window_start_time`	GLOBAL	00:00 +0:00	-	TTL 后台任务允许执行的时间窗口起始时间。
`ttl_job_schedule_window_end_time`	GLOBAL	23:59 +0:00	-	TTL 后台任务允许执行的时间窗口结束时间。
`ttl_delete_strategy`	GLOBAL	auto	auto、single_statement、scan_then_delete	手动指定删除策略；取值为 `auto` 时由内核根据 TTL 列索引情况自动选择。已配置归档表的表始终使用 archive_then_delete 策略，不受该参数影响。
`ttl_archive_strict_row_match`	GLOBAL	ON	ON、OFF	使用归档策略时，是否严格校验每批归档与删除的行数一致。