*: update doc for binlog and diff (pingcap#1046)

op-guide/tidb-v2.1-upgrade-guide.md

@@ -5,7 +5,7 @@ category: deployment
 
 # TiDB 2.1 升级操作指南
 
-本文档适用于从 TiDB 2.0 版本（v2.0.1 及之后版本）或 TiDB 2.1 rc 版本升级到 TiDB 2.1 GA 版本。2.1 版本 TiDB-Binlog 不兼容 Kafka 版本，如果当前集群已经使用 Kafka 版本的 TiDB-Binlog，升级需要参考 [Binlog 升级方法](../tools/tidb-binlog-cluster.md#版本升级方法)。
+本文档适用于从 TiDB 2.0 版本（v2.0.1 及之后版本）或 TiDB 2.1 RC 版本升级到 TiDB 2.1 GA 版本。TiDB 2.1 版本不兼容 Kafka 版本的 TiDB-Binlog，如果当前集群已经使用 [Kafka 版本的 TiDB-Binlog](../tools/tidb-binlog-kafka.md)，须参考 [Binlog 升级方法](../tools/tidb-binlog-cluster.md#版本升级方法)升级到 Cluster 版本。
 
 ## 升级兼容性说明
 
@@ -113,4 +113,4 @@ $ ansible-playbook rolling_update.yml
 
 ```
 $ ansible-playbook rolling_update_monitor.yml
-```
+```

tools/sync-diff-inspector.md

@@ -6,6 +6,7 @@ category: tools
 # sync-diff-inspector 用户文档
 
 ## sync-diff-inspector 简介
+
 sync-diff-inspector 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具，该工具提供了修复数据的功能（适用于修复少量不一致的数据）。
 
 主要功能：
@@ -20,6 +21,7 @@ GitHub 地址：[sync-diff-inspector](https://github.com/pingcap/tidb-tools/tree
 下载地址：[sync-diff-inspector-linux-amd64.tar.gz](https://download.pingcap.org/sync-diff-inspector-linux-amd64.tar.gz)
 
 ## sync-diff-inspector 的使用
+
 ### 通用配置文件说明
 
 ``` toml
@@ -59,8 +61,10 @@ schema = "test"
 tables = ["test1", "test2", "test3"]
 
 # 支持使用正则表达式配置检查的表，需要以‘~’开始，
-# 例如：下面的配置会检查所有表名以‘test’为前缀的表
-# tables = ["~test*"]
+# 下面的配置会检查所有表名以‘test’为前缀的表
+# tables = ["~^test.*"]
+# 下面的配置会检查配置库中所有的表
+# tables = ["~^"]
 
 # 对部分表进行特殊的配置，配置的表必须包含在 check-tables 中
 [[table-config]]
@@ -131,7 +135,8 @@ password = ""
 # snapshot = "2016-10-08 16:45:26"
 ```
 
-### 分库分表场景下数据对比的配置示例：
+### 分库分表场景下数据对比的配置示例
+
 假设有两个 MySQL 实例，使用同步工具同步到一个 TiDB 中，场景如图所示：
 
 ![shard-table-sync](../media/shard-table-sync.png)
@@ -207,8 +212,15 @@ password = ""
 ```
 
 ### 运行 sync-diff-inspector
+
 执行如下命令：
 
 ``` bash
 ./bin/sync_diff_inspector --config=./config.toml
-```
+```
+
+该命令最终会在日志中输出一个检查报告，说明每个表的检查情况。如果数据存在不一致的情况，sync-diff-inspector 会生成 SQL 修复不一致的数据，并将这些 SQL 语句保存到 `fix.sql` 文件中。
+
+### 注意
+
+TiDB 使用的 collation 为 utf8_bin，如果对 MySQL 和 TiDB 的数据进行对比，需要注意 MySQL 中表的 collation 设置。如果表的主键／唯一键为 varchar 类型，且 MySQL 中 collation 设置与 TiDB 不同，可能会因为排序问题导致最终校验结果不正确，需要在 sync-diff-inspector 的配置文件中增加 collation 设置。

tools/tidb-binlog-cluster.md

@@ -54,7 +54,7 @@ Pump 和 Drainer 都支持部署和运行在 Intel x86-64 架构的 64 位通用
 * Drainer 不支持对 ignore schemas（在过滤列表中的 schemas）的 table 进行 rename DDL 操作。
 * 在已有的 TiDB 集群中启动 Drainer，一般需要全量备份并且获取 savepoint，然后导入全量备份，最后启动 Drainer 从 savepoint 开始同步增量数据。
 * Drainer 支持将 Binlog 同步到 MySQL、TiDB、Kafka 或者本地文件。如果需要将 Binlog 同步到其他类型的目的地中，可以设置 Drainer 将 Binlog 同步到 Kafka，再读取 Kafka 中的数据进行自定义处理，参考 [binlog slave client 用户文档](../tools/binlog-slave-client.md)。
-* 如果 TiDB-Binlog 用于增量恢复，可以设置下游为 `pb` 将 binlog 同步到本地文件中，再使用 [Reparo](../tools/reparo.md) 恢复增量数据。
+* 如果 TiDB-Binlog 用于增量恢复，可以设置下游为 `pb`，drainer 会将 binlog 转化为指定的 proto buffer 格式的数据，再写入到本地文件中。这样就可以使用 [Reparo](../tools/reparo.md) 恢复增量数据。
 * Pump/Drainer 的状态需要区分已暂停（paused）和下线（offline），Ctrl + C 或者 kill 进程，Pump 和 Drainer 的状态都将变为 paused。暂停状态的 Pump 不需要将已保存的 Binlog 数据全部发送到 Drainer；如果需要较长时间退出 Pump（或不再使用该 Pump），需要使用 binlogctl 工具来下线 Pump。Drainer 同理。
 * 如果下游为 MySQL/TiDB，数据同步后可以使用 [sync-diff-inspector](../tools/sync-diff-inspector.md) 进行数据校验。
 
@@ -205,7 +205,7 @@ Pump 和 Drainer 都支持部署和运行在 Intel x86-64 架构的 64 位通用
 
         ```toml
         # downstream storage, equal to --dest-db-type
-        # Valid values are "mysql", "pb", "kafka", "flash", "tidb".
+        # Valid values are "mysql", "pb", "kafka", "flash".
         db-type = "mysql"
 
         # the downstream MySQL protocol database
@@ -219,7 +219,7 @@ Pump 和 Drainer 都支持部署和运行在 Intel x86-64 架构的 64 位通用
         # size-limit = "100000"
         ```
 
-    - 以下游为 pb 为例
+    - 以下游为 proto buffer（pb）格式的本地文件为例
 
         ```bash
         $ cd /home/tidb/tidb-ansible/conf
@@ -231,7 +231,7 @@ Pump 和 Drainer 都支持部署和运行在 Intel x86-64 架构的 64 位通用
 
         ```toml
         # downstream storage, equal to --dest-db-type
-        # Valid values are "mysql", "pb", "kafka", "flash", "tidb".
+        # Valid values are "mysql", "pb", "kafka", "flash".
         db-type = "pb"
 
         # Uncomment this if you want to use `pb` or `sql` as `db-type`.
@@ -380,7 +380,7 @@ Drainer="192.168.0.13"
         -data-dir string
             Drainer 数据存储位置路径 (默认 "data.drainer")
         -dest-db-type string
-            Drainer 下游服务类型 (默认为 mysql，支持 kafka、pb、flash、tidb)
+            Drainer 下游服务类型 (默认为 mysql，支持 kafka、pb、flash)
         -detect-interval int
             向 PD 查询在线 Pump 的时间间隔 (默认 10，单位 秒)
         -disable-detect
@@ -447,7 +447,7 @@ Drainer="192.168.0.13"
         disable-dispatch = false
 
         # Drainer 下游服务类型（默认为 mysql）
-        # 参数有效值为 "mysql"，"pb"，"kafka"，"flash"，"tidb"
+        # 参数有效值为 "mysql"，"pb"，"kafka"，"flash"
         db-type = "mysql"
 
         # replicate-do-db 配置的优先级高于 replicate-do-table。如果配置了相同的库名，支持使用正则表达式进行配置。
@@ -573,9 +573,11 @@ Usage of binlogctl:
     ```bash
     bin/binlogctl -pd-urls=http://127.0.0.1:2379 -cmd pumps/drainers
 
-    2018/06/21 11:24:10 nodes.go:53: [info] pump: &{NodeID:ip-192-168-199-118:8250 Host:127.0.0.1:8250 IsAlive:true IsOffline:false LatestFilePos:{Suffix:0 Offset:15320} LatestKafkaPos:{Suffix:0 Offset:382} OfflineTS:0}
+    2018/12/18 03:17:09 nodes.go:46: [info] pump: &{NodeID:1.1.1.1:8250 Addr:pump:8250 State:online IsAlive:false Score:0 Label:<nil> MaxCommitTS:405039487358599169 UpdateTS:405027205608112129}
     ```
 
+    注意：IsAlive，Score 以及 Label 字段目前没有使用，不需要关注这几个值。
+
 - 修改 Pump/Drainer 的状态
 
     Pump/Drainer 的状态可以为：online，pausing，paused，closing 以及 offline。
@@ -615,7 +617,15 @@ Usage of binlogctl:
 
 ## 版本升级方法
 
-Cluster 版本的 TiDB-Binlog 不兼容 Kafka 版本以及 Local 版本，TiDB 如果升级到新版（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）后只能使用 Cluster 版本的 TiDB-Binlog；如果在升级前已经使用了 Kafka／Local 版本的 TiDB-Binlog，必须将其升级到 Cluster 版本。
+新版本的 TiDB（v2.0.8-binlog、v2.1.0-rc.5 及以上版本）不兼容 [Kafka 版本](../tools/tidb-binlog-kafka.md)以及 [Local 版本](../tools/tidb-binlog.md)的 TiDB-Binlog，集群升级到新版本后只能使用 Cluster 版本的 TiDB-Binlog。如果在升级前已经使用了 Kafka／Local 版本的 TiDB-Binlog，必须将其升级到 Cluster 版本。
+
+ TiDB-Binlog 版本与 TiDB 版本的对应关系如下：
+
+| TiDB-Binlog 版本 | TiDB 版本 | 说明 |
+|---|---|---|
+| Local | TiDB 1.0 及更低版本 ||
+| Kafka | TiDB 1.0 ~ TiDB 2.1 RC5 | TiDB 1.0 支持 local 版本和 Kafka 版本的 TiDB-Binlog。 |
+| Cluster | TiDB v2.0.8-binlog，TiDB 2.1 RC5 及更高版本 | TiDB v2.0.8-binlog 是一个支持 Cluster 版本 TiDB-Binlog 的 2.0 特殊版本。 |
 
 升级流程：