TiDB Binlog 集群部署

服务器要求

Pump 和 Drainer 均可部署和运行在 Intel x86-64 架构的 64 位通用硬件服务器平台上。在开发、测试和生产环境下，对服务器硬件配置的要求和建议如下：

使用 TiUP 部署 TiDB Binlog

推荐使用 TiUP 部署 TiDB Binlog。即在使用 TiUP 部署 TiDB 时，在拓扑文件中添加 TiDB Binlog 的 drainer 和 pump 节点信息后，再随 TiDB 一起部署。详细部署方式参考 TiUP 部署 TiDB 集群。

使用 Binary 部署 TiDB Binlog

下载官方 Binary

1. wget https://download.pingcap.org/tidb-{version}-linux-amd64.tar.gz &&
2. wget https://download.pingcap.org/tidb-{version}-linux-amd64.sha256

检查文件完整性，返回 ok 则正确：

1. sha256sum -c tidb-{version}-linux-amd64.sha256

对于 v2.1.0 GA 及以上版本，Pump 和 Drainer 已经包含在 TiDB 的下载包中，其他版本需要单独下载 Pump 和 Drainer:

1. wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.tar.gz &&
2. wget https://download.pingcap.org/tidb-binlog-latest-linux-amd64.sha256

检查文件完整性，返回 ok 则正确：

1. sha256sum -c tidb-binlog-latest-linux-amd64.sha256

使用样例

假设有三个 PD，一个 TiDB，另外有两台机器用于部署 Pump，一台机器用于部署 Drainer。各个节点信息如下：

1. TiDB="192.168.0.10"
2. PD1="192.168.0.16"
3. PD2="192.168.0.15"
4. PD3="192.168.0.14"
5. Pump="192.168.0.11"
6. Pump="192.168.0.12"
7. Drainer="192.168.0.13"

下面以此为例，说明 Pump/Drainer 的使用。

1. 使用 binary 部署 Pump

2. Pump 命令行参数说明（以在 “192.168.0.11” 上部署为例）

   1. Usage of Pump: 2. -L string 3. 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") 4. -V 5. 打印版本信息 6. -addr string 7. Pump 提供服务的 RPC 地址(-addr="192.168.0.11:8250") 8. -advertise-addr string 9. Pump 对外提供服务的 RPC 地址(-advertise-addr="192.168.0.11:8250") 10. -config string 11. 配置文件路径，如果你指定了配置文件，Pump 会首先读取配置文件的配置; 12. 如果对应的配置在命令行参数里面也存在，Pump 就会使用命令行参数的配置来覆盖配置文件里的配置。 13. -data-dir string 14. Pump 数据存储位置路径 15. -gc int 16. Pump 只保留多少天以内的数据 (默认 7) 17. -heartbeat-interval int 18. Pump 向 PD 发送心跳间隔 (单位 秒) 19. -log-file string 20. log 文件路径 21. -log-rotate string 22. log 文件切换频率，hour/day 23. -metrics-addr string 24. Prometheus Pushgateway 地址，不设置则禁止上报监控信息 25. -metrics-interval int 26. 监控信息上报频率 (默认 15，单位 秒) 27. -node-id string 28. Pump 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 29. -pd-urls string 30. PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") 31. -fake-binlog-interval int 32. Pump 节点生成 fake binlog 的频率 (默认 3，单位 秒) - Pump 配置文件（以在 “192.168.0.11” 上部署为例）

   ``` 1. # Pump Configuration

   1. Pump 绑定的地址

   2. addr = "192.168.0.11:8250"

   3. Pump 对外提供服务的地址

   4. advertise-addr = "192.168.0.11:8250"

   5. Pump 只保留多少天以内的数据 (默认 7)

   6. gc = 7

   7. Pump 数据存储位置路径

   8. data-dir = "data.pump"

   9. Pump 向 PD 发送心跳的间隔 (单位 秒)

   10. heartbeat-interval = 2

   11. PD 集群节点的地址 (英文逗号分割，中间不加空格)

   12. pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379"

   13. [security]

   14. 如无特殊安全设置需要，该部分一般都注解掉

   15. 包含与集群连接的受信任 SSL CA 列表的文件路径

   16. ssl-ca = "/path/to/ca.pem"

   17. 包含与集群连接的 PEM 形式的 X509 certificate 的路径

   18. ssl-cert = "/path/to/drainer.pem"

   19. 包含与集群链接的 PEM 形式的 X509 key 的路径

   20. ssl-key = "/path/to/drainer-key.pem"

   21. [storage]

   22. 设置为 true（默认值）来保证可靠性，确保 binlog 数据刷新到磁盘

   23. sync-log = true

   24. 当可用磁盘容量小于该设置值时，Pump 将停止写入数据

   25. 42 MB -> 42000000, 42 mib -> 44040192

   26. default: 10 gib

   27. stop-write-at-available-space = "10 gib"

   28. Pump 内嵌的 LSM DB 设置，除非对该部分很了解，否则一般注解掉

   29. [storage.kv]

   30. block-cache-capacity = 8388608

   31. block-restart-interval = 16

   32. block-size = 4096

   33. compaction-L0-trigger = 8

   34. compaction-table-size = 67108864

   35. compaction-total-size = 536870912

   36. compaction-total-size-multiplier = 8.0

   37. write-buffer = 67108864

   38. write-L0-pause-trigger = 24

   39. write-L0-slowdown-trigger = 17

       ```
   40. 启动示例

   1. ./bin/pump -config pump.toml

   如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。 2. 使用 binary 部署 Drainer

3. Drainer 命令行参数说明（以在 “192.168.0.13” 上部署为例）

   1. Usage of Drainer 2. -L string 3. 日志输出信息等级设置：debug，info，warn，error，fatal (默认 "info") 4. -V 5. 打印版本信息 6. -addr string 7. Drainer 提供服务的地址(-addr="192.168.0.13:8249") 8. -c int 9. 同步下游的并发数，该值设置越高同步的吞吐性能越好 (default 1) 10. -cache-binlog-count int 11. 缓存中的 binlog 数目限制（默认 8） 12. 如果上游的单个 binlog 较大导致 Drainer 出现 OOM 时，可尝试调小该值减少内存使用 13. -config string 14. 配置文件路径，Drainer 会首先读取配置文件的配置； 15. 如果对应的配置在命令行参数里面也存在，Drainer 就会使用命令行参数的配置来覆盖配置文件里面的配置 16. -data-dir string 17. Drainer 数据存储位置路径 (默认 "data.drainer") 18. -dest-db-type string 19. Drainer 下游服务类型 (默认为 mysql，支持 tidb、kafka、file) 20. -detect-interval int 21. 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒) 22. -disable-detect 23. 是否禁用冲突监测 24. -disable-dispatch 25. 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则每个 binlog 26. 按顺序依次还原成单个事务进行同步（下游服务类型为 MySQL，该项设置为 False） 27. -ignore-schemas string 28. db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")， 29. 不支持对 ignore schemas 的 table 进行 rename DDL 操作 30. -initial-commit-ts（默认为 `-1`） 31. 如果 Drainer 没有相关的断点信息，可以通过该项来设置相关的断点信息 32. 该参数值为 `-1` 时，Drainer 会自动从 PD 获取一个最新的时间戳 33. -log-file string 34. log 文件路径 35. -log-rotate string 36. log 文件切换频率，hour/day 37. -metrics-addr string 38. Prometheus Pushgateway 地址，不设置则禁止上报监控信息 39. -metrics-interval int 40. 监控信息上报频率（默认 15，单位：秒） 41. -node-id string 42. drainer 节点的唯一识别 ID，如果不指定，程序会根据主机名和监听端口自动生成 43. -pd-urls string 44. PD 集群节点的地址 (-pd-urls="http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379") 45. -safe-mode 46. 是否开启安全模式使得下游 MySQL/TiDB 可被重复写入 47. 即将 insert 语句换为 replace 语句，将 update 语句拆分为 delete + replace 语句 48. -txn-batch int 49. 输出到下游数据库一个事务的 SQL 数量（默认 1） - Drainer 配置文件（以在 “192.168.0.13” 上部署为例）

   ``` 1. # Drainer Configuration.

   1. Drainer 提供服务的地址("192.168.0.13:8249")

   2. addr = "192.168.0.13:8249"

   3. Drainer 对外提供服务的地址

   4. advertise-addr = "192.168.0.13:8249"

   5. 向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒)

   6. detect-interval = 10

   7. Drainer 数据存储位置路径 (默认 "data.drainer")

   8. data-dir = "data.drainer"

   9. PD 集群节点的地址 (英文逗号分割，中间不加空格)

   10. pd-urls = "http://192.168.0.16:2379,http://192.168.0.15:2379,http://192.168.0.14:2379"

   11. log 文件路径

   12. log-file = "drainer.log"

   13. Drainer 从 Pump 获取 binlog 时对数据进行压缩，值可以为 "gzip"，如果不配置则不进行压缩

   14. compressor = "gzip"

   15. [security]

   16. 如无特殊安全设置需要，该部分一般都注解掉

   17. 包含与集群连接的受信任 SSL CA 列表的文件路径

   18. ssl-ca = "/path/to/ca.pem"

   19. 包含与集群连接的 PEM 形式的 X509 certificate 的路径

   20. ssl-cert = "/path/to/pump.pem"

   21. 包含与集群链接的 PEM 形式的 X509 key 的路径

   22. ssl-key = "/path/to/pump-key.pem"

   23. Syncer Configuration

   24. [syncer]

   25. 如果设置了该项，会使用该 sql-mode 解析 DDL 语句，此时如果下游是 MySQL 或 TiDB 则

   26. 下游的 sql-mode 也会被设置为该值

   27. sql-mode = "STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION"

   28. 输出到下游数据库一个事务的 SQL 语句数量 (默认 20)

   29. txn-batch = 20

   30. 同步下游的并发数，该值设置越高同步的吞吐性能越好 (默认 16)

   31. worker-count = 16

   32. 是否禁用拆分单个 binlog 的 SQL 的功能，如果设置为 true，则按照每个 binlog

   33. 顺序依次还原成单个事务进行同步（下游服务类型为 MySQL, 该项设置为 False）

   34. disable-dispatch = false

   35. safe mode 会使写下游 MySQL/TiDB 可被重复写入

   36. 会用 replace 替换 insert 语句，用 delete + replace 替换 update 语句

   37. safe-mode = false

   38. Drainer 下游服务类型（默认为 mysql）

   39. 参数有效值为 "mysql"，"tidb"，"file"，"kafka"

   40. db-type = "mysql"

   41. 事务的 commit ts 若在该列表中，则该事务将被过滤，不会同步至下游

   42. ignore-txn-commit-ts = []

   43. db 过滤列表 (默认 "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql,test")，

   44. 不支持对 ignore schemas 的 table 进行 rename DDL 操作

   45. ignore-schemas = "INFORMATION_SCHEMA,PERFORMANCE_SCHEMA,mysql"

   46. replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。

   47. 以 '~' 开始声明使用正则表达式

   48. replicate-do-db = ["~^b.*","s1"]

   49. [syncer.relay]

   50. 保存 relay log 的目录，空值表示不开启。

   51. 只有下游是 TiDB 或 MySQL 时该配置才生效。

   52. log-dir = ""

   53. 每个文件的大小上限

   54. max-file-size = 10485760

   55. [[syncer.replicate-do-table]]

   56. db-name ="test"

   57. tbl-name = "log"

   58. [[syncer.replicate-do-table]]

   59. db-name ="test"

   60. tbl-name = "~^a.*"

   61. 忽略同步某些表

   62. [[syncer.ignore-table]]

   63. db-name = "test"

   64. tbl-name = "log"

   65. db-type 设置为 mysql 时，下游数据库服务器参数

   66. [syncer.to]
   67. host = "192.168.0.13"
   68. user = "root"

   69. 如果你不想在配置文件中写明文密码，则可以使用 ./binlogctl -cmd encrypt -text string 生成加密的密码

   70. 如果配置了 encrypted_password 且非空，那么配置的 password 不生效。encrypted_password 和 password 无法同时生效。

   71. password = ""
   72. encrypted_password = ""

   73. port = 3306

   74. [syncer.to.checkpoint]

   75. 当 checkpoint type 是 mysql 或 tidb 时可以开启该选项，以改变保存 checkpoint 的数据库

   76. schema = "tidb_binlog"

   77. 目前只支持 mysql 或者 tidb 类型。可以去掉注释来控制 checkpoint 保存的位置。

   78. db-type 默认的 checkpoint 保存方式是:

   79. mysql/tidb -> 对应的下游 mysql/tidb

   80. file/kafka -> file in data-dir

   81. type = "mysql"

   82. host = "127.0.0.1"

   83. user = "root"

   84. password = ""

   85. 使用 ./binlogctl -cmd encrypt -text string 加密的密码

   86. encrypted_password 非空时 password 会被忽略

   87. encrypted_password = ""

   88. port = 3306

   89. db-type 设置为 file 时，存放 binlog 文件的目录

   90. [syncer.to]

   91. dir = "data.drainer"

   92. db-type 设置为 kafka 时，Kafka 相关配置

   93. [syncer.to]

   94. kafka-addrs 和 zookeeper-addrs 只需要一个，两者都有时程序会优先用 zookeeper 中的 kafka 地址

   95. zookeeper-addrs = "127.0.0.1:2181"

   96. kafka-addrs = "127.0.0.1:9092"

   97. kafka-version = "0.8.2.0"

   98. 配置单条 broker request 中的最大 message 数（即 binlog 数），不配置或配置小于等于 0 时会使用默认值 1024

   99. kafka-max-messages = 1024

   100. 配置单条 broker request 的最大 size（单位为 Byte），默认为 1 GiB，最大可配置为 2 GiB

   101. kafka-max-message-size = 1073741824

   102. 保存 binlog 数据的 Kafka 集群的 topic 名称，默认值为 _obinlog

   103. 如果运行多个 Drainer 同步数据到同一个 Kafka 集群，每个 Drainer 的 topic-name 需要设置不同的名称

   104. topic-name = ""

        ```
   105. 启动示例

   注意：

   如果下游为 MySQL/TiDB，为了保证数据的完整性，在 Drainer 初次启动前需要获取 initial-commit-ts 的值，并进行全量数据的备份与恢复。

   初次启动时使用参数 initial-commit-ts， 命令如下：

   1. ./bin/drainer -config drainer.toml -initial-commit-ts {initial-commit-ts}

   如果命令行参数与配置文件中的参数重合，则使用命令行设置的参数的值。

注意：

• 在运行 TiDB 时，需要保证至少一个 Pump 正常运行。
• 通过给 TiDB 增加启动参数 enable-binlog 来开启 binlog 服务。尽量保证同一集群的所有 TiDB 都开启了 binlog 服务，否则在同步数据时可能会导致上下游数据不一致。如果要临时运行一个不开启 binlog 服务的 TiDB 实例，需要在 TiDB 的配置文件中设置 run_ddl= false。
• Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。
• 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取快照时间戳，然后导入全量备份，最后启动 Drainer 从对应的快照时间戳开始同步增量数据。
• 下游使用 MySQL 或 TiDB 时应当保证上下游数据库的 sql_mode 具有一致性，即下游数据库同步每条 SQL 语句时的 sql_mode 应当与上游数据库执行该条 SQL 语句时的 sql_mode 保持一致。可以在上下游分别执行 select @@sql_mode; 进行查询和比对。
• 如果存在上游 TiDB 能运行但下游 MySQL 不支持的 DDL 语句时（例如下游 MySQL 使用 InnoDB 引擎时同步语句 CREATE TABLE t1(a INT) ROW_FORMAT=FIXED;），Drainer 也会同步失败，此时可以在 Drainer 配置中跳过该事务，同时在下游手动执行兼容的语句，详见跳过事务。