TDSQL Boundless TTL (Time to Live)

一、概述

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 声明归档写入撞上归档表主键/唯一键时的处理方式；具体语法如下：

— 建表时一并指定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 查询。

十二、相关参数