遇到 TiDB 执行 alter table 报错或 DDL 任务堆积时，优先使用ADMIN SHOW DDL JOBS查看队列状态，确认任务是正在运行、排队还是暂停。对于正在运行的重负载 DDL，可通过ADMIN ALTER DDL JOBS调整并发参数加速；对于因升级等原因暂停的任务，使用ADMIN RESUME DDL JOBS恢复。

命令速用版

以下命令可直接在 TiDB 客户端执行，用于查看和调整 DDL 任务。

-- 查看 DDL 任务队列及状态
ADMIN SHOW DDL JOBS;

-- 调整正在运行的 DDL 任务并发度（例如 job_id 为 101）
ADMIN ALTER DDL JOBS 101 THREAD=8;

-- 恢复处于暂停状态的 DDL 任务
ADMIN RESUME DDL JOBS 101;

为什么会这样

TiDB 的 DDL 操作是分布式执行的，重负载操作如添加索引需要回填数据，会占用系统资源并进入队列等待。

TiDB 支持在线 DDL，不会阻塞 DML 操作，但添加索引等重型操作需要背填数据，耗时取决于表大小。系统通过tidb_ddl_reorg_worker_cnt等变量控制资源消耗。当多个 DDL 同时提交或集群处于升级后的暂停状态时，任务会堆积在队列中，导致新任务无法立即执行或报错。

分步处理

按照以下步骤排查和处理 DDL 队列拥堵问题。

1. 查看当前 DDL 任务状态

执行ADMIN SHOW DDL JOBS，结果中的STATE列显示任务状态，ID列显示 job_id。如果任务处于running状态但进度缓慢，可考虑调整参数；如果处于paused状态，需恢复任务。

2. 加速正在运行的任务

对于状态为running的ADD INDEX、MODIFY COLUMN或REORGANIZE PARTITION任务，可使用ADMIN ALTER DDL JOBS修改参数。例如将并发度调整为 8：

ADMIN ALTER DDL JOBS 101 THREAD=8;

也可同时调整批处理大小：

ADMIN ALTER DDL JOBS 101 THREAD=8, BATCH_SIZE=256;

3. 恢复暂停的任务

如果集群刚完成版本升级，正在运行的 DDL 可能被自动暂停。确认 job_id 后执行：

ADMIN RESUME DDL JOBS 101;

支持同时恢复多个任务，用逗号分隔 job_id。

怎么验证是否生效

执行调整后，再次运行ADMIN SHOW DDL JOBS。

检查COMMENTS列，部分版本会显示当前参数值。观察STATE列，暂停的任务应变为运行中。对于调整并发的任务，监控集群资源使用情况，确认背填速度是否有提升。

常见坑

操作 DDL 任务时需注意以下限制，避免操作失败。

• 仅支持特定类型：ADMIN ALTER DDL JOBS仅支持ADD INDEX、MODIFY COLUMN和REORGANIZE PARTITION，其他类型会返回 unsupported DDL operation 错误。
• 仅针对运行中任务：如果 DDL 任务不存在或已完成，执行 alter 会返回 ddl job is not running 错误。
• 不支持批量修改参数：目前只能通过ADMIN ALTER DDL JOBS修改单个 DDL job 的参数，不支持同时修改多个 job_id 的参数。
• 重复恢复报错：如果重复恢复同一个 DDL 作业，会报错 Error Number: 8261。

常见问题

DDL 任务调整后参数立即生效吗？

是的，ADMIN ALTER DDL JOBS仅对正在运行的 DDL job 生效，修改后任务会按新参数继续执行。

所有 DDL 类型都能调整并发度吗？

不是，目前仅ADD INDEX、MODIFY COLUMN和REORGANIZE PARTITION支持调整THREAD和BATCH_SIZE参数。

升级后 DDL 任务不见了怎么办？

如果尝试恢复已经完成的 DDL 任务，会在 RESULT 列看到 DDL Job:not found 的错误，表示该任务已从 DDL 等待队列中被移除，无需恢复。

参考来源

• TiDB Docs, ADMIN ALTER DDL JOBS
• TiDB Docs, ADMIN RESUME DDL JOBS
• TiDB Docs, SQL FAQs | TiDB Docs
• TiDB Docs, TiDB 集群问题导图