sync-diff-inspector 用户文档

    sync-diff-inspector 是一个用于校验 MySQL／TiDB 中两份数据是否一致的工具。该工具提供了修复数据的功能（适用于修复少量不一致的数据）。

    主要功能：

    可通过以下方式下载 sync-diff-inspector：

    • 对于 MySQL 和 TiDB 之间的数据同步不支持在线校验，需要保证上下游校验的表中没有数据写入，或者保证某个范围内的数据不再变更，通过配置 来校验这个范围内的数据。

    • 不支持 JSON、BIT、BINARY、BLOB 等类型的数据，在校验时需要设置 ignore-columns 忽略检查这些类型的数据。

    • FLOAT、DOUBLE 等浮点数类型在 TiDB 和 MySQL 中的实现方式不同，在计算 checksum 时可能存在差异，如果发现因为这些类型的数据导致的数据校验不一致，需要设置 ignore-columns 忽略这些列的检查。

    • 支持对不包含主键或者唯一索引的表进行校验，但是如果数据不一致，生成的用于修复的 SQL 可能无法正确修复数据。

    sync-diff-inspector 需要获取表结构信息、查询数据、建 checkpoint 库保存断点信息，需要的数据库权限如下：

      • SELECT（查数据进行对比）

      • SHOW_DATABASES (查看库名)

      • RELOAD (查看表结构)

    • 下游数据库

      • SELECT （查数据进行对比）

      • CREATE （创建 checkpoint 库和表）

      • DELETE （删除 checkpoint 表中的信息）

      • INSERT （写入 checkpoint 表）

      • UPDATE（修改 checkpoint 表）

      • RELOAD (查看表结构)

    sync-diff-inspector 的配置总共分为三个部分：

    • Global config: 通用配置，包括日志级别、划分 chunk 的大小、校验的线程数量等。
    • Tables config: 配置校验哪些表，如果有的表在上下游有一定的映射关系或者有一些特殊要求，则需要对指定的表进行配置。
    • Databases config: 配置上下游数据库实例。

    下面是一个完整配置文件的说明：

    1. # Diff Configuration.
    3. ######################### Global config #########################
    5. # 日志级别，可以设置为 info、debug
    6. log-level = "info"
    8. # sync-diff-inspector 根据主键／唯一键／索引将数据划分为多个 chunk，
    9. # 对每一个 chunk 的数据进行对比。使用 chunk-size 设置 chunk 的大小
    10. chunk-size = 1000
    12. # 检查数据的线程数量
    13. check-thread-count = 4
    15. # 抽样检查的比例，如果设置为 100 则检查全部数据
    16. sample-percent = 100
    18. # 通过计算 chunk 的 checksum 来对比数据，如果不开启则逐行对比数据
    19. use-checksum = true
    21. # 如果设置为 true 则只会通过计算 checksum 来校验数据，如果上下游的 checksum 不一致也不会查出数据再进行校验
    22. only-use-checksum = false
    24. # 是否使用上次校验的 checkpoint，如果开启，则只校验上次未校验以及校验失败的 chunk
    25. use-checkpoint = true
    26. # 不对比数据
    27. ignore-data-check = false
    29. # 不对比表结构
    30. ignore-struct-check = false
    32. # 保存用于修复数据的 sql 的文件名称
    33. fix-sql-file = "fix.sql"
    35. ######################### Tables config #########################
    37. # 如果需要对比大量的不同库名或者表名的表的数据，或者用于校验上游多个分表与下游总表的数据，可以通过 table-rule 来设置映射关系
    38. # 可以只配置 schema 或者 table 的映射关系，也可以都配置
    39. #[[table-rules]]
    40.     # schema-pattern 和 table-pattern 支持通配符 *?
    41.     #schema-pattern = "test_*"
    42.     #table-pattern = "t_*"
    43.     #target-schema = "test"
    44.     #target-table = "t"
    46. # 配置需要对比的*目标数据库*中的表
    47. [[check-tables]]
    49.     schema = "test"
    51.     # 需要检查的表
    52.     tables = ["test1", "test2", "test3"]
    54.     # 支持使用正则表达式配置检查的表，需要以‘~’开始，
    55.     # 下面的配置会检查所有表名以‘test’为前缀的表
    56.     # tables = ["~^test.*"]
    57.     # 下面的配置会检查配置库中所有的表
    58.     # tables = ["~^"]
    60. # 对部分表进行特殊的配置，配置的表必须包含在 check-tables 中
    61. [[table-config]]
    62.     # 目标库中数据库的名称
    63.     schema = "test"
    65.     # 表名
    66.     table = "test3"
    68.     # 指定用于划分 chunk 的列，如果不配置该项，sync-diff-inspector 会选取一个合适的列（主键／唯一键／索引）
    69.     index-field = "id"
    71.     # 指定检查的数据的范围，需要符合 sql 中 where 条件的语法
    72.     range = "age > 10 AND age < 20"
    74.     # 如果是对比多个分表与总表的数据，则设置为 true
    75.     is-sharding = false
    77.     # 在某些情况下字符类型的数据的排序会不一致，通过指定 collation 来保证排序的一致，
    78.     # 需要与数据库中 charset 的设置相对应
    79.     # collation = "latin1_bin"
    81.     # 忽略某些列的检查，例如 sync-diff-inspector 目前还不支持的一些类型（json，bit，blob 等），
    82.     # 或者是浮点类型数据在 TiDB 和 MySQL 中的表现可能存在差异，可以使用 ignore-columns 忽略检查这些列
    83.     # ignore-columns = ["name"]
    85. [[table-config]]
    86.     # 目标库名
    87.     schema = "test"
    89.     # 目标表名
    90.     table = "test2"
    92.     # 非分库分表场景，设置为 false
    93.     is-sharding = false
    95.     # 源数据的配置
    96.     [[table-config.source-tables]]
    97.         # 源库的实例 id
    99.         # 源数据库的名称
    100.         schema = "test"
    101.         # 源表的名称
    102.         table  = "test1"
    104. ######################### Databases config #########################
    106. # 源数据库实例的配置
    107. [[source-db]]
    108.     host = "127.0.0.1"
    109.     port = 3306
    110.     user = "root"
    111.     password = "123456"
    112.     # 源数据库实例的 id，唯一标识一个数据库实例
    113.     instance-id = "source-1"
    114.     # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比
    115.     # snapshot = "2016-10-08 16:45:26"
    116.     # 设置数据库的 sql-mode，用于解析表结构
    117.     # sql-mode = ""
    119. # 目标数据库实例的配置
    120. [target-db]
    121.     host = "127.0.0.1"
    122.     port = 4000
    123.     user = "root"
    124.     password = "123456"
    125.     # 使用 TiDB 的 snapshot 功能，如果开启的话会使用历史数据进行对比
    126.     # snapshot = "2016-10-08 16:45:26"
    127.     # 设置数据库的 sql-mode，用于解析表结构
    128.     # sql-mode = ""

    执行如下命令：

    该命令最终会在日志中输出一个检查报告，说明每个表的检查情况。如果数据存在不一致的情况，sync-diff-inspector 会生成 SQL 修复不一致的数据，并将这些 SQL 语句保存到 fix.sql 文件中。

    日志

    sync-diff-inspector 会在运行时定期（间隔 10s）输出校验进度到日志中，格式如下：

    1. [2020/11/12 17:47:00.170 +08:00] [INFO] [checkpoint.go:276] ["summary info"] [instance_id=target] [schema=test] [table=test_table] ["chunk num"=1000] ["success num"=80] ["failed num"=1] ["ignore num"=0]
    • chunk num：总共需要校验的 chunk 数量。
    • success num：已经校验数据一致的 chunk 数量。
    • failed num：校验失败的 chunk 数量。校验时遇到错误和数据不一致两种情况都属于校验失败。
    • ignore num：被忽略校验的 chunk 数量。当配置项 sample-percent 的值小于 100 时，sync-diff-inspector 会采用抽样的方式校验数据，这样就会有部分 chunk 被忽略校验。

    校验结果

    当校验结束时，sync-diff-inspector 会输出一份校验报告。

    • 数据校验一致的日志示例如下：

    • 数据校验不一致或者遇到错误时的日志示例如下：

      1.   [2020/11/12 18:16:17.068 +08:00] [INFO] [checkpoint.go:276] ["summary info"] [instance_id=target] [schema=test] [table=test1] ["chunk num"=1] ["success num"=0] ["failed num"=1] ["ignore num"=0]
      2.   [2020/11/12 18:16:17.071 +08:00] [INFO] [report.go:80] ["check result summary"] ["check passed num"=0] ["check failed num"=1]
      3.   [2020/11/12 18:16:17.071 +08:00] [INFO] [report.go:87] ["table check result"] [schema=test] [table=test_table] ["struct equal"=true] ["data equal"=false]
      4.   [2020/11/12 18:16:17.071 +08:00] [INFO] [main.go:75] ["check data finished"] [cost=319.849706ms]
      5.   [2020/11/12 18:16:17.071 +08:00] [WARN] [main.go:66] ["check failed!!!"]
    • sync-diff-inspector 在校验数据时会消耗一定的服务器资源，需要避免在业务高峰期间校验。
    • TiDB 使用的 collation 为 utf8_bin。如果对 MySQL 和 TiDB 的数据进行对比，需要注意 MySQL 中表的 collation 设置。如果表的主键／唯一键为 varchar 类型，且 MySQL 中 collation 设置与 TiDB 不同，可能会因为排序问题导致最终校验结果不正确，需要在 sync-diff-inspector 的配置文件中增加 collation 设置。
    • sync-diff-inspector 会优先使用 TiDB 的统计信息来划分 chunk，需要尽量保证统计信息精确，可以在业务空闲期手动执行 analyze table {table_name}。
    • 生成的 fix.sql 仅作为修复数据的参考，需要确认后再执行这些 SQL 修复数据。