ticdc: fix wrong names in bidirectional replication (#21928)

releases/release-6.5.0.md

@@ -328,7 +328,7 @@ Compared with TiDB [6.4.0-DMR](/releases/release-6.4.0.md), TiDB 6.5.0 introduce
 | [`tidb_cdc_write_source`](/system-variables.md#tidb_cdc_write_source-new-in-v650) | Newly added | When this variable is set to a value other than 0, data written in this session is considered to be written by TiCDC. This variable can only be modified by TiCDC. Do not manually modify this variable in any case. |
 | [`tidb_enable_plan_replayer_capture`](/system-variables.md#tidb_enable_plan_replayer_capture) | Newly added | The feature controlled by this variable is not fully functional in TiDB v6.5.0. Do not change the default value. |
 | [`tidb_index_merge_intersection_concurrency`](/system-variables.md#tidb_index_merge_intersection_concurrency-new-in-v650) | Newly added | Sets the maximum concurrency for the intersection operations that index merge performs. It is effective only when TiDB accesses partitioned tables in the dynamic pruning mode. |
-| [`tidb_source_id`](/system-variables.md#tidb_source_id-new-in-v650) | Newly added | This variable is used to configure the different cluster IDs in a [bi-directional replication](/ticdc/ticdc-bidirectional-replication.md) cluster.|
+| [`tidb_source_id`](/system-variables.md#tidb_source_id-new-in-v650) | Newly added | This variable is used to configure the different cluster IDs in a [bidirectional replication](/ticdc/ticdc-bidirectional-replication.md) cluster.|
 | [`tidb_sysproc_scan_concurrency`](/system-variables.md#tidb_sysproc_scan_concurrency-new-in-v650) | Newly added | This variable is used to set the concurrency of scan operations performed when TiDB executes internal SQL statements (such as an automatic update of statistics). The default value is `1`. |
 | [`tidb_ttl_delete_batch_size`](/system-variables.md#tidb_ttl_delete_batch_size-new-in-v650) | Newly added | This variable is used to set the maximum number of rows that can be deleted in a single `DELETE` transaction in a TTL job. |
 | [`tidb_ttl_delete_rate_limit`](/system-variables.md#tidb_ttl_delete_rate_limit-new-in-v650) | Newly added | This variable is used to limit the maximum number of `DELETE` statements allowed per second in a single node in a TTL job. When this variable is set to `0`, no limit is applied. |

system-variables.md

@@ -3814,13 +3814,13 @@ For details, see [Identify Slow Queries](/identify-slow-queries.md).
 
 <CustomContent platform="tidb">
 
-- This variable is used to configure the different cluster IDs in a [bi-directional replication](/ticdc/ticdc-bidirectional-replication.md) cluster.
+- This variable is used to configure the different cluster IDs in a [bidirectional replication](/ticdc/ticdc-bidirectional-replication.md) cluster.
 
 </CustomContent>
 
 <CustomContent platform="tidb-cloud">
 
-- This variable is used to configure the different cluster IDs in a [bi-directional replication](https://docs.pingcap.com/tidb/stable/ticdc-bidirectional-replication) cluster.
+- This variable is used to configure the different cluster IDs in a [bidirectional replication](https://docs.pingcap.com/tidb/stable/ticdc-bidirectional-replication) cluster.
 
 </CustomContent>
 

ticdc/ticdc-bidirectional-replication.md

@@ -5,13 +5,17 @@ summary: Learn how to use bidirectional replication of TiCDC.
 
 # Bidirectional Replication
 
+<<<<<<< HEAD
 Starting from v6.5.0, TiCDC supports bi-directional replication among two TiDB clusters. Based on this feature, you can create a multi-active TiDB solution using TiCDC.
+=======
+TiCDC supports bidirectional replication (BDR) among two TiDB clusters. Based on this feature, you can create a multi-active TiDB solution using TiCDC.
+>>>>>>> 1e9dac24d7 (ticdc: fix wrong names in bidirectional replication (#21928))
 
-This section describes how to use bi-directional replication taking two TiDB clusters as an example.
+This section describes how to use bidirectional replication taking two TiDB clusters as an example.
 
-## Deploy bi-directional replication
+## Deploy bidirectional replication
 
-TiCDC only replicates incremental data changes that occur after a specified timestamp to the downstream cluster. Before starting the bi-directional replication, you need to take the following steps:
+TiCDC only replicates incremental data changes that occur after a specified timestamp to the downstream cluster. Before starting the bidirectional replication, you need to take the following steps:
 
 1. (Optional) According to your needs, import the data of the two TiDB clusters into each other using the data export tool [Dumpling](/dumpling-overview.md) and data import tool [TiDB Lightning](/tidb-lightning/tidb-lightning-overview.md).
 
@@ -21,25 +25,30 @@ TiCDC only replicates incremental data changes that occur after a specified time
 
 3. Specify the starting time point of data replication for the upstream and downstream clusters.
 
-    1. Check the time point of the upstream and downstream clusters. In the case of two TiDB clusters, make sure that data in the two clusters are consistent at certain time points. For example, the data of TiDB A at `ts=1` and the data of TiDB B at `ts=2` are consistent.
+    1. Check the time point of the upstream and downstream clusters. In the case of two TiDB clusters, make sure that data in the two clusters are consistent at certain time points. For example, the data of TiDB 1 at `ts=1` and the data of TiDB 2 at `ts=2` are consistent.
 
-    2. When you create the changefeed, set the `--start-ts` of the changefeed for the upstream cluster to the corresponding `tso`. That is, if the upstream cluster is TiDB A, set `--start-ts=1`; if the upstream cluster is TiDB B, set `--start-ts=2`.
+    2. When you create the changefeed, set the `--start-ts` of the changefeed for the upstream cluster to the corresponding `tso`. That is, if the upstream cluster is TiDB 1, set `--start-ts=1`; if the downstream cluster is TiDB 2, set `--start-ts=2`.
 
 4. In the configuration file specified by the `--config` parameter, add the following configuration:
 
     ```toml
-    # Whether to enable the bi-directional replication mode
+    # Whether to enable the bidirectional replication mode
     bdr-mode = true
     ```
 
-After the configuration takes effect, the clusters can perform bi-directional replication.
+After the configuration takes effect, the clusters can perform bidirectional replication.
 
 ## Execute DDL
 
+<<<<<<< HEAD
 After the bidirectional replication is enabled, TiCDC does not replicate any DDL statements. You need to execute DDL statements in the upstream and downstream clusters respectively.
+=======
+Starting from v7.6.0, to support DDL replication as much as possible in bidirectional replication, TiDB divides the [DDLs that TiCDC originally supports](/ticdc/ticdc-ddl.md) into two types: replicable DDLs and non-replicable DDLs, according to the impact of DDLs on the business.
+>>>>>>> 1e9dac24d7 (ticdc: fix wrong names in bidirectional replication (#21928))
 
 Note that some DDL statements might cause table structure changes or data change time sequence problems, which might lead to data inconsistency after the replication. Therefore, after enabling bidirectional replication, only the DDL statements in the following table can be executed without stopping the write operations of the application.
 
+<<<<<<< HEAD
 | Event | Does it cause changefeed errors | Note |
 |---|---|---|
 | create database | Yes | After you manually execute the DDL statements in the upstream and downstream clusters, the errors can be automatically recovered. |
@@ -59,23 +68,149 @@ Note that some DDL statements might cause table structure changes or data change
 | alter table remove ttl | No |  |
 | add **not unique** index | No |  |
 | drop **not unique** index | No |  |
+=======
+Replicable DDLs are the DDLs that can be directly executed and replicated to other TiDB clusters in bidirectional replication.
+>>>>>>> 1e9dac24d7 (ticdc: fix wrong names in bidirectional replication (#21928))
 
 If you need to execute DDL statements that are not in the preceding table, take the following steps:
 
+<<<<<<< HEAD
 1. Pause the write operations in the tables that need to execute DDL in all clusters.
 2. After the write operations of the corresponding tables in all clusters have been replicated to other clusters, manually execute all DDL statements in each TiDB cluster.
 3. After the DDL statements are executed, resume the write operations.
+=======
+- [`ALTER TABLE ... ADD COLUMN`](/sql-statements/sql-statement-add-column.md): the column can be `null`, or has `not null` and `default value` at the same time
+- [`ALTER TABLE ... ADD INDEX`](/sql-statements/sql-statement-add-index.md) (non-unique)
+- [`ALTER TABLE ... ADD PARTITION`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... ALTER COLUMN DROP DEFAULT`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... ALTER COLUMN SET DEFAULT`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... COMMENT=...`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... DROP PRIMARY KEY`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md): you can only modify the `default value` and `comment` of the column
+- [`ALTER TABLE ... RENAME INDEX`](/sql-statements/sql-statement-rename-index.md)
+- [`ALTER TABLE ... ALTER INDEX ... INVISIBLE`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... ALTER INDEX ... VISIBLE`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE REMOVE TTL`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE TTL`](/sql-statements/sql-statement-alter-table.md)
+- [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md)
+- [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md)
+- [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md)
+- [`CREATE VIEW`](/sql-statements/sql-statement-create-view.md)
+- [`DROP INDEX`](/sql-statements/sql-statement-drop-index.md)
+- [`DROP VIEW`](/sql-statements/sql-statement-drop-view.md)
+
+### Non-replicable DDLs
+
+Non-replicable DDLs are the DDLs that have a great impact on the business, and might cause data inconsistency between clusters. Non-replicable DDLs cannot be directly replicated to other TiDB clusters in bidirectional replication through TiCDC. Non-replicable DDLs must be executed through specific operations.
+
+Non-replicable DDLs include:
+
+- [`ALTER DATABASE CHARACTER SET`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... ADD COLUMN`](/sql-statements/sql-statement-alter-table.md): the column is `not null` and does not have a `default value`
+- [`ALTER TABLE ... ADD PRIMARY KEY`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... ADD UNIQUE INDEX`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... AUTO_INCREMENT=...`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... AUTO_RANDOM_BASE=...`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... CHARACTER SET=...`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... DROP COLUMN`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... DROP PARTITION`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... EXCHANGE PARTITION`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... MODIFY COLUMN`](/sql-statements/sql-statement-modify-column.md): you can modify the attributes of the column except `default value` and `comment`
+- [`ALTER TABLE ... REORGANIZE PARTITION`](/sql-statements/sql-statement-alter-table.md)
+- [`ALTER TABLE ... TRUNCATE PARTITION`](/sql-statements/sql-statement-alter-table.md)
+- [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md)
+- [`DROP TABLE`](/sql-statements/sql-statement-drop-table.md)
+- [`RECOVER TABLE`](/sql-statements/sql-statement-recover-table.md)
+- [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md)
+- [`TRUNCATE TABLE`](/sql-statements/sql-statement-truncate.md)
+
+## DDL replication
+
+To solve the problem of replicable DDLs and non-replicable DDLs, TiDB introduces the following BDR roles:
+
+- `PRIMARY`: You can execute replicable DDLs, but not non-replicable DDLs. Replicable DDLs executed in a PRIMARY cluster will be replicated to the downstream by TiCDC.
+- `SECONDARY`: You cannot execute replicable DDLs or non-replicable DDLs. However, DDLs executed in a PRIMARY cluster can be replicated to a SECONDARY cluster by TiCDC.
+
+When no BDR role is set, you can execute any DDL. However, the changefeed in BDR mode does not replicate any DDL on that cluster.
+
+In short, in BDR mode, TiCDC only replicates replicable DDLs in the PRIMARY cluster to the downstream.
+
+### Replication scenarios of replicable DDLs
+
+1. Choose a TiDB cluster and execute `ADMIN SET BDR ROLE PRIMARY` to set it as the primary cluster.
+
+    ```sql
+    ADMIN SET BDR ROLE PRIMARY;
+    ```
+
+    ```
+    Query OK, 0 rows affected
+    Time: 0.003s
+
+    ADMIN SHOW BDR ROLE;
+    +----------+
+    | BDR_ROLE |
+    +----------+
+    | primary  |
+    +----------+
+    ```
+
+2. On other TiDB clusters, execute `ADMIN SET BDR ROLE SECONDARY` to set them as the secondary clusters.
+3. Execute **replicable DDLs** on the primary cluster. The successfully executed DDLs will be replicated to the secondary clusters by TiCDC.
+
+> **Note:**
+>
+> To prevent misuse:
+>
+> - If you try to execute **non-replicable DDLs** on the primary cluster, you will get the [Error 8263](/error-codes.md).
+> - If you try to execute **replicable DDLs** or **non-replicable DDLs** on the secondary clusters, you will get the [Error 8263](/error-codes.md).
+
+### Replication scenarios of non-replicable DDLs
+
+1. Execute `ADMIN UNSET BDR ROLE` on all TiDB clusters to unset the BDR role.
+2. Stop writing data to the tables that need to execute DDLs in all clusters.
+3. Wait until all writes to the corresponding tables in all clusters are replicated to other clusters, and then manually execute all DDLs on each TiDB cluster.
+4. Wait until the DDLs are completed, and then resume writing data.
+5. Follow the steps in [Replication scenarios of replicable DDLs](#replication-scenarios-of-replicable-ddls) to switch back to the replication scenario of replicable DDLs.
+
+> **Warning:**
+>
+> After you execute `ADMIN UNSET BDR ROLE` on all TiDB clusters, none of the DDLs are replicated by TiCDC. You need to manually execute the DDLs on each cluster separately.
+>>>>>>> 1e9dac24d7 (ticdc: fix wrong names in bidirectional replication (#21928))
 
-## Stop bi-directional replication
+## Stop bidirectional replication
 
 After the application has stopped writing data, you can insert a special record into each cluster. By checking the two special records, you can make sure that data in two clusters are consistent.
 
+<<<<<<< HEAD
 After the check is completed, you can stop the changefeed to stop bi-directional replication.
 
 ## Limitations
 
 - For the limitations of DDL, see [Execute DDL](#execute-ddl).
+=======
+After the check is completed, you can stop the changefeed to stop bidirectional replication, and execute `ADMIN UNSET BDR ROLE` on all TiDB clusters.
+
+## Limitations
+
+- Use BDR role only in the following scenarios:
+
+    - 1 `PRIMARY` cluster and n `SECONDARY` clusters (replication scenarios of replicable DDLs)
+    - n clusters that have no BDR roles (replication scenarios in which you can manually execute non-replicable DDLs on each cluster)
+
+    > **Note:**
+    >
+    > Do not set the BDR role in other scenarios, for example, setting `PRIMARY`, `SECONDARY`, and no BDR roles at the same time. If you set the BDR role incorrectly, TiDB cannot guarantee data correctness and consistency during data replication.
+
+- Usually do not use [`AUTO_INCREMENT`](/auto-increment.md) or [`AUTO_RANDOM`](/auto-random.md) to avoid data conflicts in the replicated tables. If you need to use `AUTO_INCREMENT` or `AUTO_RANDOM`, you can set different `auto_increment_increment` and `auto_increment_offset` for different clusters to ensure that different clusters can be assigned different primary keys. For example, if there are three TiDB clusters (A, B, and C) in bidirectional replication, you can set them as follows:
+
+    - In Cluster A, set `auto_increment_increment=3` and `auto_increment_offset=2000`
+    - In Cluster B, set `auto_increment_increment=3` and `auto_increment_offset=2001`
+    - In Cluster C, set `auto_increment_increment=3` and `auto_increment_offset=2002`
+
+    This way, A, B, and C will not conflict with each other in the implicitly assigned `AUTO_INCREMENT` ID and `AUTO_RANDOM` ID. If you need to add a cluster in BDR mode, you need to temporarily stop writing data of the related application, set the appropriate values for `auto_increment_increment` and `auto_increment_offset` on all clusters, and then resume writing data of the related application.
+>>>>>>> 1e9dac24d7 (ticdc: fix wrong names in bidirectional replication (#21928))
 
-- Bi-directional replication clusters cannot detect write conflicts, which might cause undefined behaviors. Therefore, you must ensure that there are no write conflicts from the application side.
+- Bidirectional replication clusters cannot detect write conflicts, which might cause undefined behaviors. Therefore, you must ensure that there are no write conflicts from the application side.
 
-- Bi-directional replication supports more than two clusters, but does not support multiple clusters in cascading mode, that is, a cyclic replication like TiDB A -> TiDB B -> TiDB C -> TiDB A. In such a topology, if one cluster fails, the whole data replication will be affected. Therefore, to enable bi-directional replication among multiple clusters, you need to connect each cluster with every other clusters, for example, `TiDB A <-> TiDB B`, `TiDB B <-> TiDB C`, `TiDB C <-> TiDB A`.
+- Bidirectional replication supports more than two clusters, but does not support multiple clusters in cascading mode, that is, a cyclic replication like TiDB A -> TiDB B -> TiDB C -> TiDB A. In such a topology, if one cluster fails, the whole data replication will be affected. Therefore, to enable bidirectional replication among multiple clusters, you need to connect each cluster with every other clusters, for example, `TiDB A <-> TiDB B`, `TiDB B <-> TiDB C`, `TiDB C <-> TiDB A`.