From f2c36e00cfab1124ac3ab6459f7c74bd360b1d65 Mon Sep 17 00:00:00 2001 From: doc-claw-bot Date: Wed, 22 Jul 2026 09:27:36 +0000 Subject: [PATCH 1/3] docs: clarify TiCDC index DDL ordering --- ticdc/ticdc-ddl.md | 2 +- ticdc/ticdc-faq.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/ticdc/ticdc-ddl.md b/ticdc/ticdc-ddl.md index e966009092a01..1658d8e130687 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -48,7 +48,7 @@ The allow list of DDL statements supported by TiCDC is as follows: ### Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs -When the downstream is TiDB, TiCDC executes `ADD INDEX` and `CREATE INDEX` DDL operations asynchronously to minimize the impact on changefeed replication latency. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB for execution, TiCDC returns immediately without waiting for the completion of the DDL execution. This avoids blocking subsequent DML executions. +Although TiCDC usually replicates DDL statements in order, `ADD INDEX` and `CREATE INDEX` are exceptions when the downstream is TiDB. To minimize the impact on changefeed replication latency, TiCDC executes these DDL operations asynchronously. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB for execution, TiCDC returns immediately without waiting for the completion of the DDL execution. This avoids blocking subsequent DML executions. During the execution of the `ADD INDEX` or `CREATE INDEX` DDL operation in the downstream, when TiCDC executes the next DDL operation of the same table, this DDL operation might be blocked in the `queueing` state for a long time. This can cause TiCDC to repeatedly execute this DDL operation, and if retries take too long, it might lead to replication task failure. Starting from v8.1.2, if TiCDC has the `SUPER` permission of the downstream database, it periodically runs `ADMIN SHOW DDL JOBS` to check the status of asynchronously executed DDL tasks. TiCDC will wait for index creation to complete before proceeding with replication. Although this might increase replication latency, it avoids replication task failure. diff --git a/ticdc/ticdc-faq.md b/ticdc/ticdc-faq.md index 6a68fa9db84ea..e9bbe1766d9bd 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -395,11 +395,13 @@ For TiCDC versions earlier than v6.5.2, it is recommended that you deploy TiCDC ## What is the order of executing DML and DDL statements? -Currently, TiCDC adopts the following order: +For most DDL statements, TiCDC adopts the following order: 1. TiCDC blocks the replication progress of the tables affected by DDL statements until the DDL `commitTS`. This ensures that DML statements executed before DDL `commitTS` can be successfully replicated to the downstream first. -2. TiCDC continues with the replication of DDL statements. If there are multiple DDL statements, TiCDC replicates them in a serial manner. -3. After the DDL statements are executed in the downstream, TiCDC will continue with the replication of DML statements executed after DDL `commitTS`. +2. TiCDC continues with the replication of DDL statements. If there are multiple DDL statements, TiCDC usually replicates them in a serial manner. +3. After the DDL statements are executed in the downstream, TiCDC continues with the replication of DML statements executed after DDL `commitTS`. + +When the downstream is TiDB, `ADD INDEX` and `CREATE INDEX` are exceptions to the preceding order. To minimize the impact on changefeed replication latency, TiCDC executes these two DDL types asynchronously and does not wait for them to finish in the downstream before returning. Therefore, these DDLs do not fully follow the preceding "wait for downstream execution to finish before continuing replication" order. For details about this special handling and later optimizations, see [Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs](/ticdc/ticdc-ddl.md#asynchronous-execution-of-add-index-and-create-index-ddls). ## How should I check whether the upstream and downstream data is consistent? From f341e5980b6a30b1857c81ac19f393d0d351969a Mon Sep 17 00:00:00 2001 From: doc-claw-bot Date: Wed, 22 Jul 2026 09:47:52 +0000 Subject: [PATCH 2/3] docs: sync TiCDC DDL wording with docs-cn review --- ticdc/ticdc-ddl.md | 2 +- ticdc/ticdc-faq.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-ddl.md b/ticdc/ticdc-ddl.md index 1658d8e130687..e13b394b6863a 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -48,7 +48,7 @@ The allow list of DDL statements supported by TiCDC is as follows: ### Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs -Although TiCDC usually replicates DDL statements in order, `ADD INDEX` and `CREATE INDEX` are exceptions when the downstream is TiDB. To minimize the impact on changefeed replication latency, TiCDC executes these DDL operations asynchronously. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB for execution, TiCDC returns immediately without waiting for the completion of the DDL execution. This avoids blocking subsequent DML executions. +Although TiCDC usually replicates DDL statements in order, when the downstream is TiDB, TiCDC executes DDL operations for creating and adding indexes asynchronously. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB for execution, TiCDC returns immediately without waiting for the completion of the DDL execution. This minimizes the impact on changefeed replication latency and avoids blocking subsequent DML executions. During the execution of the `ADD INDEX` or `CREATE INDEX` DDL operation in the downstream, when TiCDC executes the next DDL operation of the same table, this DDL operation might be blocked in the `queueing` state for a long time. This can cause TiCDC to repeatedly execute this DDL operation, and if retries take too long, it might lead to replication task failure. Starting from v8.1.2, if TiCDC has the `SUPER` permission of the downstream database, it periodically runs `ADMIN SHOW DDL JOBS` to check the status of asynchronously executed DDL tasks. TiCDC will wait for index creation to complete before proceeding with replication. Although this might increase replication latency, it avoids replication task failure. diff --git a/ticdc/ticdc-faq.md b/ticdc/ticdc-faq.md index e9bbe1766d9bd..68cdc1e672984 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -401,7 +401,7 @@ For most DDL statements, TiCDC adopts the following order: 2. TiCDC continues with the replication of DDL statements. If there are multiple DDL statements, TiCDC usually replicates them in a serial manner. 3. After the DDL statements are executed in the downstream, TiCDC continues with the replication of DML statements executed after DDL `commitTS`. -When the downstream is TiDB, `ADD INDEX` and `CREATE INDEX` are exceptions to the preceding order. To minimize the impact on changefeed replication latency, TiCDC executes these two DDL types asynchronously and does not wait for them to finish in the downstream before returning. Therefore, these DDLs do not fully follow the preceding "wait for downstream execution to finish before continuing replication" order. For details about this special handling and later optimizations, see [Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs](/ticdc/ticdc-ddl.md#asynchronous-execution-of-add-index-and-create-index-ddls). +For `ADD INDEX` and `CREATE INDEX`, when the downstream is TiDB, TiCDC executes these DDLs asynchronously and does not wait for them to finish in the downstream before returning, to minimize the impact on changefeed replication latency. For more information, see [Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs](/ticdc/ticdc-ddl.md#asynchronous-execution-of-add-index-and-create-index-ddls). ## How should I check whether the upstream and downstream data is consistent? From cd187441e90b46a8f4cab809d0f5e44d45ab2a9e Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 22 Jul 2026 18:05:31 +0800 Subject: [PATCH 3/3] Apply suggestions from code review --- ticdc/ticdc-ddl.md | 2 +- ticdc/ticdc-faq.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ticdc/ticdc-ddl.md b/ticdc/ticdc-ddl.md index e13b394b6863a..cf4f820e62c7f 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -48,7 +48,7 @@ The allow list of DDL statements supported by TiCDC is as follows: ### Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs -Although TiCDC usually replicates DDL statements in order, when the downstream is TiDB, TiCDC executes DDL operations for creating and adding indexes asynchronously. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB for execution, TiCDC returns immediately without waiting for the completion of the DDL execution. This minimizes the impact on changefeed replication latency and avoids blocking subsequent DML executions. +Although TiCDC usually replicates DDL statements in order, when the downstream is TiDB, TiCDC executes DDL operations for creating and adding indexes asynchronously. This means that, after replicating `ADD INDEX` and `CREATE INDEX` DDLs to the downstream TiDB cluster for execution, TiCDC returns immediately without waiting for DDL execution to complete. This minimizes the impact on changefeed replication latency and avoids blocking subsequent DML executions. During the execution of the `ADD INDEX` or `CREATE INDEX` DDL operation in the downstream, when TiCDC executes the next DDL operation of the same table, this DDL operation might be blocked in the `queueing` state for a long time. This can cause TiCDC to repeatedly execute this DDL operation, and if retries take too long, it might lead to replication task failure. Starting from v8.1.2, if TiCDC has the `SUPER` permission of the downstream database, it periodically runs `ADMIN SHOW DDL JOBS` to check the status of asynchronously executed DDL tasks. TiCDC will wait for index creation to complete before proceeding with replication. Although this might increase replication latency, it avoids replication task failure. diff --git a/ticdc/ticdc-faq.md b/ticdc/ticdc-faq.md index 68cdc1e672984..086af5ecc8fd3 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -401,7 +401,7 @@ For most DDL statements, TiCDC adopts the following order: 2. TiCDC continues with the replication of DDL statements. If there are multiple DDL statements, TiCDC usually replicates them in a serial manner. 3. After the DDL statements are executed in the downstream, TiCDC continues with the replication of DML statements executed after DDL `commitTS`. -For `ADD INDEX` and `CREATE INDEX`, when the downstream is TiDB, TiCDC executes these DDLs asynchronously and does not wait for them to finish in the downstream before returning, to minimize the impact on changefeed replication latency. For more information, see [Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs](/ticdc/ticdc-ddl.md#asynchronous-execution-of-add-index-and-create-index-ddls). +For `ADD INDEX` and `CREATE INDEX`, when the downstream is TiDB, TiCDC executes these DDLs asynchronously and does not wait for them to finish executing in the downstream before returning, to minimize the impact on changefeed replication latency. For more information, see [Asynchronous execution of `ADD INDEX` and `CREATE INDEX` DDLs](/ticdc/ticdc-ddl.md#asynchronous-execution-of-add-index-and-create-index-ddls). ## How should I check whether the upstream and downstream data is consistent?