pingcap · ti-chi-bot · Jan 18, 2024 · Dec 21, 2023 · Dec 21, 2023 · Dec 21, 2023
diff --git a/TOC.md b/TOC.md
@@ -706,6 +706,7 @@
       - [`ADMIN PAUSE DDL`](/sql-statements/sql-statement-admin-pause-ddl.md)
       - [`ADMIN RECOVER INDEX`](/sql-statements/sql-statement-admin-recover.md)
       - [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md)
+      - [`ADMIN [SET|SHOW] BDR ROLE`](/sql-statements/sql-statement-admin-bdr-role.md)
       - [`ADMIN SHOW DDL [JOBS|QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md)
       - [`ADMIN SHOW TELEMETRY`](/sql-statements/sql-statement-admin-show-telemetry.md)
       - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md)

diff --git a/error-codes.md b/error-codes.md
@@ -445,6 +445,10 @@ TiDB 兼容 MySQL 的错误码，在大多数情况下，返回和 MySQL 一样
 
     DDL 已经被 `ADMIN PAUSE` 暂停，无法再次执行。
 
+* Error Number: 8263
+
+    该 DDL 无法在特定的 BDR role 下执行。请确定该集群是否处于[双向复制](/ticdc/ticdc-bidirectional-replication.md) 中。如果集群没有在双向复制中，可以通过 `ADMIN SET BDR ROLE LOCAL_ONLY;` 使 DDL 恢复正常使用。
+
 * Error Number: 9001
 
     完整的报错信息为 `ERROR 9001 (HY000) : PD Server Timeout`。

diff --git a/sql-statements/sql-statement-admin-bdr-role.md b/sql-statements/sql-statement-admin-bdr-role.md
@@ -0,0 +1,64 @@
+---
+title: ADMIN [SET|SHOW] BDR ROLE
+summary: TiDB 数据库中 ADMIN [SET|SHOW] BDR ROLE 的使用概况。
+---
+
+# ADMIN [SET|SHOW] BDR ROLE
+
+- `ADMIN SET BDR ROLE` 可以设置该集群的 BDR role。现在 TiDB 集群可以设置 `PRIMARY`、`SECONDARY` 和 `LOCAL_ONLY`（默认）三种 BDR role。关于 BDR role 的详细信息可参考 [TiCDC 双向复制的 DDL 同步](/ticdc/ticdc-bidirectional-replication.md#ddl-同步)。
+- `ADMIN SHOW BDR ROLE` 可以显示该集群的 BDR role。
+
+> **警告：**
+>
+> 双向复制的 DDL 同步目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+## 语法图
+
+```ebnf+diagram
+AdminShowBDRRoleStmt ::=
+    'ADMIN' 'SHOW' 'BDR' 'ROLE'
+
+AdminSetBDRRoleStmt ::=
+    'ADMIN' 'SET' 'BDR' 'ROLE' ('PRIMARY' | 'SECONDARY' | 'LOCAL_ONLY')
+```
+
+## 示例
+
+TiDB 集群的默认 BDR role 是 `LOCAL_ONLY`。
+
+```sql
+ADMIN SHOW BDR ROLE;
+```
+
+```sql
++------------+
+| BDR_ROLE   |
++------------+
+| local_only |
++------------+
+1 row in set (0.01 sec)
+```
+
+执行以下命令可以将 BDR role 设置为 `PRIMARY`。
+
+```sql
+ADMIN SET BDR ROLE PRIMARY;
+```
+
+```sql
+Query OK, 0 rows affected (0.01 sec)
+```
+
+```sql
+ADMIN SHOW BDR ROLE;
++----------+
+| BDR_ROLE |
++----------+
+| primary  |
++----------+
+1 row in set (0.00 sec)
+```
+
+## MySQL 兼容性
+
+`ADMIN [SET|SHOW] BDR ROLE` 语句是 TiDB 对 MySQL 语法的扩展。
diff --git a/ticdc/ticdc-bidirectional-replication.md b/ticdc/ticdc-bidirectional-replication.md
@@ -5,7 +5,7 @@ summary: 了解 TiCDC 双向复制的使用方法。
 
 # TiCDC 双向复制
 
-从 v6.5.0 版本开始，TiCDC 支持在两个 TiDB 集群之间进行双向复制。基于该功能，你可以使用 TiCDC 来构建 TiDB 集群的多写多活解决方案。
+从 v6.5.0 版本开始，TiCDC 支持在两个 TiDB 集群之间进行双向复制 (Bidirectional replication, BDR)。基于该功能，你可以使用 TiCDC 来构建 TiDB 集群的多写多活解决方案。
 
 本文档以在两个 TiDB 集群之间进行双向复制为例，介绍双向复制的使用方法。
 
@@ -34,47 +34,112 @@ TiCDC 复制功能只会将指定时间点之后的增量变更复制到下游
 
 这样，以上搭建好的集群即可对数据进行双向复制。
 
-## 执行 DDL
-
-开启双向复制功能后，TiCDC 不会同步任何 DDL。用户需要自行在上下游集群中分别执行 DDL。
-
-需要注意的是，某些 DDL 会造成表结构变更或者数据更改时序问题，从而导致数据同步后出现不一致的情况。因此，在开启双向同步功能后，只有下表中的 DDL 可以在业务不停止数据写入的情况下执行。
-
-| 事件                        | 是否会引起 changefeed 错误 | 说明    |
-| ---------------------------- | ------ |--------------------------|
-| create database              | 是     | 用户手动在上下游都执行了 DDL 之后，错误可以自动恢复|
-| drop database                | 是     | 需要手动重启 changefeed，指定 `--overwrite-checkpoint-ts` 为该条 DDL 的commitTs 来恢复         |
-| create table                 | 是   | 用户手动在上下游都执行了 DDL 之后，错误可以自动恢复       |
-| drop table                   | 是   | 需要手动重启 changefeed，指定 `--overwrite-checkpoint-ts` 为该条 ddl 的commitTs 来恢复        |
-| alter table comment          | 否   |    |
-| rename index                 | 否   |    |
-| alter table index visibility | 否   |    |
-| add partition                | 是   | 用户手动在上下游都执行了 DDL 之后，错误可以自动恢复    |
-| drop partition               | 否   |    |
-| create view                  | 否   |    |
-| drop view                    | 否   |    |
-| alter column default value   | 否  |    |
-| reorganize partition         | 是   | 用户手动在上下游都执行了 DDL 之后，错误可以自动恢复    |
-| alter table ttl              | 否   |    |
-| alter table remove ttl       | 否   |    |
-| add **not unique** index     | 否   |    |
-| drop **not unique** index    | 否   |    |
-
-如果需要执行以上列表中不存在的 DDL，需要采取以下步骤：
-
-1. 暂停所有集群中需要执行 DDL 的对应的表的写入操作。
-2. 等待所有集群中对应表的所有写入已经同步到其他集群后，手动在每一个 TiDB 集群上单独执行所有的 DDL。
-3. 等待 DDL 完成之后，重新恢复写入。
+## DDL 类别
+
+从 v7.6.0 开始，为了在双向复制中尽可能地支持 DDL 同步，根据 DDL 对业务的影响，TiDB 将 [TiCDC 原本支持同步的 DDL](/ticdc/ticdc-ddl.md) 划分为两种 DDL：可复制的 DDL 和不可复制的 DDL。
+
+### 可复制的 DDL
+
+可复制的 DDL 是指在双向复制中，可以直接执行并同步到其他 TiDB 集群的 DDL。
+
+可复制的 DDL 包括：
+
+- `CREATE DATABASE`
+- `CREATE TABLE`
+- `ADD COLUMN`：添加的列必须是 `not null` 或者带有 `default value` 的列
+- `ADD NON-UNIQUE INDEX`
+- `DROP INDEX`
+- `MODIFY COLUMN`：仅能修改列的 `default value` 和 `comment`
+- `ALTER COLUMN DEFAULT VALUE`
+- `MODIFY TABLE COMMENT`
+- `RENAME INDEX`
+- `ADD TABLE PARTITION`
+- `DROP PRIMARY KEY`
+- `ALTER TABLE INDEX VISIBILITY`
+- `ALTER TABLE TTL`
+- `ALTER TABLE REMOVE TTL`
+- `CREATE VIEW`
+- `DROP VIEW`
+
+### 不可复制的 DDL
+
+不可复制的 DDL 是指对业务影响较大、不能在双向复制中直接通过 TiCDC 同步到其他 TiDB 集群的 DDL。不可复制的 DDL 必须通过特定的操作来执行。
+
+不可复制的 DDL 包括：
+
+- `DROP DATABASE`
+- `DROP TABLE`
+- `ADD COLUMN`：添加的列为 `null` 且不带有 `default value` 的列
+- `DROP COLUMN`
+- `ADD UNIQUE INDEX`
+- `TRUNCATE TABLE`
+- `MODIFY COLUMN`：修改列除 `default value` 和 `comment` 以外的属性
+- `RENAME TABLE`
+- `DROP PARTITION`
+- `TRUNCATE PARTITION`
+- `ALTER TABLE CHARACTER SET`
+- `ALTER DATABASE CHARACTER SET`
+- `RECOVER TABLE`
+- `ADD PRIMARY KEY`
+- `REBASE AUTO ID`
+- `EXCHANGE PARTITION`
+- `REORGANIZE PARTITION`
+
+## DDL 同步
+
+为了能够解决上述可复制的 DDL 和不可复制的 DDL 两类 DDL 的同步问题，TiDB 引入了三种 BDR role：
+
+- `LOCAL_ONLY`（默认）：你可以执行任意 DDL，但是在 TiCDC 开启 `bdr_mode=true` 之后，执行的 DDL 不会被 TiCDC 同步。
+- `PRIMARY`：你可以执行可复制的 DDL，但不能执行不可复制的 DDL，可复制的 DDL 会被 TiCDC 同步到下游。
+- `SECONDARY`：你不能执行可复制的 DDL，也不能执行不可复制的 DDL，但是会执行从 TiCDC 同步过来的 DDL。
+
+> **警告：**
+>
+> 双向复制的 DDL 同步目前为实验特性，不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 [issue](https://github.com/pingcap/tidb/issues) 反馈。
+
+### 可复制的 DDL 的同步场景
+
+1. 选择一个 TiDB 集群，执行 `ADMIN SET BDR ROLE PRIMARY` 将其设置为主集群。
+2. 在其他 TiDB 集群上，执行 `ADMIN SET BDR ROLE SECONDARY` 将其设置为从集群。
+3. 在主集群上执行**可复制的 DDL**，执行成功的 DDL 会被 TiCDC 同步到从集群中。
+
+> **注意：**
+>
+> 为了防止误操作：
+>
+> - 如果在主集群中尝试执行**不可复制的 DDL**，会[报错 8263](/error-codes.md)。
+> - 无论在从集群中尝试执行**可复制的 DDL** 还是**不可复制的 DDL**，都会[报错 8263](/error-codes.md)。
+
+### 不可复制的 DDL 的同步场景
+
+1. 在所有的 TiDB 集群的上执行 `ADMIN SET BDR ROLE LOCAL_ONLY`，将其 BDR role 设置为 `LOCAL_ONLY`（默认值）。
+2. 暂停所有集群中需要执行 DDL 的对应的表的写入操作。
+3. 等待所有集群中对应表的所有写入已经同步到其他集群后，手动在每一个 TiDB 集群上单独执行所有的 DDL。
+4. 等待 DDL 完成之后，重新恢复写入。
+5. 按照[可复制的 DDL 的同步场景](#可复制的-ddl-的同步场景)的操作步骤，切换回可复制的 DDL 的同步场景。
 
 ## 停止双向复制
 
 在业务数据停止写入之后，你可以在两个集群中都插入一行特殊的值，通过检查这两行特殊的值来确保数据达到了一致的状态。
 
-检查完毕之后，停止同步任务即可停止双向复制。
+检查完毕之后，停止同步任务，并把 BDR role 切换回 `LOCAL_ONLY` 即可停止双向复制。
 
 ## 使用限制
 
-- DDL 的限制见[执行 DDL 小节](#执行-ddl)。
+- BDR role 只能在以下两种场景中正常使用：
+
+    - 1 个 `PRIMARY` 集群和 n 个 `SECONDARY` 集群（可复制的 DDL 的同步场景）
+    - n 个 `LOCAL_ONLY` 集群（不可复制的 DDL 的同步场景）
+
+    **注意，请勿将 BDR role 设置为其他情况，例如，同时设置了 `PRIMARY`、`SECONDARY`、`LOCAL_ONLY`。如果错误地设置了 BDR role，TiDB 无法保证数据正确性。**
+
+- 一般情况下，禁止在同步的表中使用 `AUTO_INCREMENT` 或 `AUTO_RANDOM` 键，以免产生数据冲突的问题。如果需要使用 `AUTO_INCREMENT` 或 `AUTO_RANDOM` 键，可以通过在不同的集群设置 `auto_increment_increment` 和 `auto_increment_offset` 来使得不同的集群都能够分配到不同的 primary key。假设有三台 TiDB（A、B、C）处于双向同步中，那么你可以采取如下设置：
+
+    - 在 A 中设置 `auto_increment_increment=3`，`auto_increment_offset=2000`
+    - 在 B 中设置 `auto_increment_increment=3`，`auto_increment_offset=2001`
+    - 在 C 中设置 `auto_increment_increment=3`，`auto_increment_offset=2002`
+
+  这样的话，A、B、C 隐式分配到的 `AUTO_INCREMENT` ID 和 `AUTO_RANDOM` ID 就不会互相冲突。如果需要增加 BDR 模式的集群，则要临时暂停相关业务的写入，重新在所有集群上设置合适的 `auto_increment_increment` 和 `auto_increment_offset` 后，再开启相关业务。
 
 - 双向复制的集群不具备检测写冲突的功能，写冲突将会导致未定义问题。你需要在业务层面保证不出现写冲突。