From 0869e07d0a5696dbf4d1153c856007b1fd42c5dd 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 c575ae4215454..c13c9fafee44d 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -61,7 +61,7 @@ The following is the allow list of DDL statements supported by TiCDC. The abbrev ### 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.4.0, 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 aa9f1a98398f4..95e5a9fe65c4d 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -413,11 +413,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 348fac6768c9861a9d8331b47982f8d4d9263960 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 c13c9fafee44d..16a113e7f9756 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -61,7 +61,7 @@ The following is the allow list of DDL statements supported by TiCDC. The abbrev ### 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.4.0, 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 95e5a9fe65c4d..36ba4bace36e3 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -419,7 +419,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 a58a942c78c15c81180a640c6a59f2eb4dbdc021 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 16a113e7f9756..985d4dad2db3c 100644 --- a/ticdc/ticdc-ddl.md +++ b/ticdc/ticdc-ddl.md @@ -61,7 +61,7 @@ The following is the allow list of DDL statements supported by TiCDC. The abbrev ### 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.4.0, 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 36ba4bace36e3..0b182d9e5b307 100644 --- a/ticdc/ticdc-faq.md +++ b/ticdc/ticdc-faq.md @@ -419,7 +419,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?