From 2e3398d42824c7e5ec50fecb28880652662afc7b Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 13 Jul 2020 10:43:41 +0800 Subject: [PATCH 1/4] cherry pick #3916 to release-3.0 Signed-off-by: ti-srebot --- TOC.md | 221 +++++++ br/backup-and-restore-tool.md | 575 ++++++++++++++++++ export-or-backup-using-dumpling.md | 2 +- table-filter.md | 251 ++++++++ ticdc/manage-ticdc.md | 555 +++++++++++++++++ .../tidb-lightning-configuration.md | 12 +- tidb-lightning/tidb-lightning-glossary.md | 16 +- 7 files changed, 1621 insertions(+), 11 deletions(-) create mode 100644 br/backup-and-restore-tool.md create mode 100644 table-filter.md create mode 100644 ticdc/manage-ticdc.md diff --git a/TOC.md b/TOC.md index 2166f439eb39..7c47763aec00 100644 --- a/TOC.md +++ b/TOC.md @@ -6,6 +6,7 @@ ## 目录 + 关于 TiDB +<<<<<<< HEAD - [TiDB 简介](/overview.md) + Benchmark 测试 - [如何用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md) @@ -73,6 +74,226 @@ - [集群配置诊断](/troubleshoot-tidb-cluster.md) - [TiDB Lightning 故障诊断](/troubleshoot-tidb-lightning.md) + 参考手册 +======= + + [TiDB 简介](/overview.md) + + [What's New in TiDB 4.0](/whats-new-in-tidb-4.0.md) + + [基本功能](/basic-features.md) + + 兼容性 + + [与 MySQL 的兼容性](/mysql-compatibility.md) + + [使用限制](/tidb-limitations.md) + + [荣誉列表](/credits.md) ++ 快速上手 + + [快速上手指南](/quick-start-with-tidb.md) + + [SQL 基本操作](/basic-sql-operations.md) ++ 部署集群 + + [软硬件环境需求](/hardware-and-software-requirements.md) + + [环境与系统配置检查](/check-before-deployment.md) + + 配置拓扑结构 + + [最小部署拓扑结构](/minimal-deployment-topology.md) + + [TiFlash 部署拓扑](/tiflash-deployment-topology.md) + + [TiCDC 部署拓扑](/ticdc-deployment-topology.md) + + [TiDB Binlog 部署拓扑](/tidb-binlog-deployment-topology.md) + + [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) + + [混合部署拓扑结构](/hybrid-deployment-topology.md) + + 安装与启动 + + Linux 环境 + + [使用 TiUP 部署（推荐）](/production-deployment-using-tiup.md) + + [使用 TiUP 离线部署（推荐）](/production-offline-deployment-using-tiup.md) + + [使用 Ansible 部署](/online-deployment-using-ansible.md) + + [使用 Ansible 离线部署](/offline-deployment-using-ansible.md) + + [验证集群状态](/post-installation-check.md) + + 性能测试报告及重现指南 + + [如何用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md) + + [如何对 TiDB 进行 TPC-C 测试](/benchmark/benchmark-tidb-using-tpcc.md) + + [Sysbench 性能对比 - v4.0 对比 v3.0](/benchmark/benchmark-sysbench-v4-vs-v3.md) + + [TPC-H 性能对比 - v4.0 对比 v3.0](/benchmark/v4.0-performance-benchmarking-with-tpch.md) + + [TPC-C 性能对比 - v4.0 对比 v3.0](/benchmark/v4.0-performance-benchmarking-with-tpcc.md) + + [Sysbench 性能对比 - v3.0 对比 v2.1](/benchmark/v3.0-performance-benchmarking-with-sysbench.md) + + [TPC-C 性能对比 - v3.0 对比 v2.1](/benchmark/v3.0-performance-benchmarking-with-tpcc.md) + + [线上负载与 ADD INDEX 相互影响测试](/benchmark/online-workloads-and-add-index-operations.md) ++ 数据迁移 + + [概述](/migration-overview.md) + + 从 MySQL 迁移至 TiDB + + [从 Mydumper 文件迁移](/migrate-from-mysql-mydumper-files.md) + + [使用 DM 工具从 Amazon Aurora MySQL 迁移](/migrate-from-aurora-mysql-database.md) + + 从 CSV 文件迁移至 TiDB + + [使用 TiDB Lightning 导入 CSV 文件](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) + + [使用 LOAD DATA 语句导入 CSV 文件](/sql-statements/sql-statement-load-data.md) + + [从 SQL 文件迁移到 TiDB](/migrate-from-mysql-mydumper-files.md) ++ 运维操作 + + 升级 TiDB 版本 + + [使用 TiUP 升级（推荐）](/upgrade-tidb-using-tiup.md) + + [使用 TiUP 离线升级（推荐）](/upgrade-tidb-using-tiup-offline.md) + + [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/upgrade-a-tidb-cluster) + + [使用 TiDB Ansible](/upgrade-tidb-using-ansible.md) + + 扩缩容 + + [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) + + [使用 TiDB Ansible](/scale-tidb-using-ansible.md) + + [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/scale-a-tidb-cluster) + + 备份与恢复 + + 使用 BR 工具（推荐） + + [使用 BR 进行备份与恢复](/br/backup-and-restore-tool.md) + + [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md) + + [使用 Dumpling 和 TiDB Lightning 进行备份与恢复（推荐）](/backup-and-restore-using-dumpling-lightning.md) + + [使用 Mydumper 和 TiDB Lightning 进行备份与恢复](/backup-and-restore-using-mydumper-lightning.md) + + [读取历史数据](/read-historical-data.md) + + [修改时区](/configure-time-zone.md) + + [日常巡检](/daily-check.md) + + [TiCDC 运维操作及任务管理](/ticdc/manage-ticdc.md) + + [TiFlash 常用运维操作](/tiflash/maintain-tiflash.md) + + [TiUP 常用运维操作](/maintain-tidb-using-tiup.md) + + [Ansible 常用运维操作](/maintain-tidb-using-ansible.md) ++ 监控与告警 + + [监控框架概述](/tidb-monitoring-framework.md) + + [监控 API](/tidb-monitoring-api.md) + + [手动部署监控](/deploy-monitoring-services.md) + + [TiDB 集群报警规则与处理方法](/alert-rules.md) + + [TiFlash 报警规则与处理方法](/tiflash/tiflash-alert-rules.md) ++ 故障诊断 + + [定位慢查询](/identify-slow-queries.md) + + [SQL 诊断](/system-tables/system-table-sql-diagnostics.md) + + [定位消耗系统资源多的查询](/identify-expensive-queries.md) + + [SQL 语句统计](/statement-summary-tables.md) + + [TiDB 集群常见问题](/troubleshoot-tidb-cluster.md) + + [TiDB 集群问题导图](/tidb-troubleshooting-map.md) + + [热点问题处理](/troubleshoot-hot-spot-issues.md) + + [CPU 占用过多导致读写延迟增加](/troubleshoot-cpu-issues.md) + + [写冲突与写性能下降](/troubleshoot-write-conflicts.md) + + [磁盘 I/O 过高](/troubleshoot-high-disk-io.md) + + [锁冲突与 TTL 超时](/troubleshoot-lock-conflicts.md) + + [TiCDC 常见问题](/ticdc/troubleshoot-ticdc.md) + + [TiFlash 常见问题](/tiflash/troubleshoot-tiflash.md) ++ 性能调优 + + 系统调优 + + [操作系统性能参数调优](/tune-operating-system.md) + + 软件调优 + + 配置 + + [TiDB 内存调优](/configure-memory-usage.md) + + [TiKV 线程调优](/tune-tikv-thread-performance.md) + + [TiKV 内存调优](/tune-tikv-memory-performance.md) + + [TiKV Follower Read](/follower-read.md) + + [TiFlash 调优](/tiflash/tune-tiflash-performance.md) + + [下推计算结果缓存](/coprocessor-cache.md) + + SQL 性能调优 + + [SQL 性能调优概览](/sql-tuning-overview.md) + + [理解 TiDB 执行计划](/query-execution-plan.md) + + SQL 优化 + + [SQL 优化流程简介](/sql-optimization-concepts.md) + + 逻辑优化 + + [逻辑优化概览](/sql-logical-optimization.md) + + [子查询相关的优化](/subquery-optimization.md) + + [列裁剪](/column-pruning.md) + + [关联子查询去关联](/correlated-subquery-optimization.md) + + [Max/Min 消除](/max-min-eliminate.md) + + [谓词下推](/predicate-push-down.md) + + [分区裁剪](/partition-pruning.md) + + [TopN 和 Limit 下推](/topn-limit-push-down.md) + + [Join Reorder](/join-reorder.md) + + 物理优化 + + [物理优化概览](/sql-physical-optimization.md) + + [索引的选择](/choose-index.md) + + [统计信息简介](/statistics.md) + + [错误索引的解决方案](/wrong-index-solution.md) + + [Distinct 优化](/agg-distinct-optimization.md) + + [执行计划缓存](/sql-prepare-plan-cache.md) + + 控制执行计划 + + [控制执行计划概览](/control-execution-plan.md) + + [Optimizer Hints](/optimizer-hints.md) + + [执行计划管理](/sql-plan-management.md) + + [优化规则及表达式下推的黑名单](/blacklist-control-plan.md) ++ 教程 + + [同城多中心部署](/multi-data-centers-in-one-city-deployment.md) + + [两地三中心部署](/three-data-centers-in-two-cities-deployment.md) + + 最佳实践 + + [TiDB 最佳实践](/best-practices/tidb-best-practices.md) + + [Java 应用开发最佳实践](/best-practices/java-app-best-practices.md) + + [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) + + [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) + + [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) + + [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) + + [海量 Region 集群调优](/best-practices/massive-regions-best-practices.md) + + [Placement Rules 使用文档](/configure-placement-rules.md) + + [Load Base Split 使用文档](/configure-load-base-split.md) + + [Store Limit 使用文档](/configure-store-limit.md) ++ TiDB 生态工具 + + [功能概览](/ecosystem-tool-user-guide.md) + + [适用场景](/ecosystem-tool-user-case.md) + + [工具下载](/download-ecosystem-tools.md) + + Backup & Restore (BR) + + [BR 常见问题](/br/backup-and-restore-faq.md) + + [使用 BR 进行备份和恢复](/br/backup-and-restore-tool.md) + + [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md) + + TiDB Binlog + + [概述](/tidb-binlog/tidb-binlog-overview.md) + + [快速上手](/tidb-binlog/get-started-with-tidb-binlog.md) + + [部署使用](/tidb-binlog/deploy-tidb-binlog.md) + + [运维管理](/tidb-binlog/maintain-tidb-binlog-cluster.md) + + [配置说明](/tidb-binlog/tidb-binlog-configuration-file.md) + + [Pump](/tidb-binlog/tidb-binlog-configuration-file.md#pump) + + [Drainer](/tidb-binlog/tidb-binlog-configuration-file.md#drainer) + + [版本升级](/tidb-binlog/upgrade-tidb-binlog.md) + + [监控告警](/tidb-binlog/monitor-tidb-binlog-cluster.md) + + [增量恢复](/tidb-binlog/tidb-binlog-reparo.md) + + [binlogctl 工具](/tidb-binlog/binlog-control.md) + + [Kafka 自定义开发](/tidb-binlog/binlog-slave-client.md) + + [TiDB Binlog Relay Log](/tidb-binlog/tidb-binlog-relay-log.md) + + [集群间双向同步](/tidb-binlog/bidirectional-replication-between-tidb-clusters.md) + + [术语表](/tidb-binlog/tidb-binlog-glossary.md) + + 故障诊断 + + [故障诊断](/tidb-binlog/troubleshoot-tidb-binlog.md) + + [常见错误修复](/tidb-binlog/handle-tidb-binlog-errors.md) + + [FAQ](/tidb-binlog/tidb-binlog-faq.md) + + TiDB Lightning + + [概述](/tidb-lightning/tidb-lightning-overview.md) + + [快速上手教程](/get-started-with-tidb-lightning.md) + + [部署执行](/tidb-lightning/deploy-tidb-lightning.md) + + [参数说明](/tidb-lightning/tidb-lightning-configuration.md) + + 主要功能 + + [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md) + + [表库过滤](/table-filter.md) + + [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) + + [TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md) + + [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md) + + [监控告警](/tidb-lightning/monitor-tidb-lightning.md) + + [故障诊断](/troubleshoot-tidb-lightning.md) + + [FAQ](/tidb-lightning/tidb-lightning-faq.md) + + [术语表](/tidb-lightning/tidb-lightning-glossary.md) + + [TiCDC](/ticdc/ticdc-overview.md) + + [Dumpling](/dumpling-overview.md) + + sync-diff-inspector + + [概述](/sync-diff-inspector/sync-diff-inspector-overview.md) + + [不同库名或表名的数据校验](/sync-diff-inspector/route-diff.md) + + [分库分表场景下的数据校验](/sync-diff-inspector/shard-diff.md) + + [TiDB 主从集群的数据校验](/sync-diff-inspector/upstream-downstream-diff.md) + + [Loader](/loader-overview.md) + + [Mydumper](/mydumper-overview.md) + + [Syncer](/syncer-overview.md) + + TiSpark + + [TiSpark 快速上手](/get-started-with-tispark.md) + + [TiSpark 用户指南](/tispark-overview.md) ++ 参考指南 + + 架构 + + [概述](/tidb-architecture.md) + + [存储](/tidb-storage.md) + + [计算](/tidb-computing.md) + + [调度](/tidb-scheduling.md) + + 监控指标 + + [Overview 面板](/grafana-overview-dashboard.md) + + [TiDB 面板](/grafana-tidb-dashboard.md) + + [PD 面板](/grafana-pd-dashboard.md) + + [TiKV 面板](/grafana-tikv-dashboard.md) + + [TiFlash 监控指标](/tiflash/monitor-tiflash.md) + + 安全加固 + + [为 TiDB 客户端服务端间通信开启加密传输](/enable-tls-between-clients-and-servers.md) + + [为 TiDB 组件间通信开启加密传输](/enable-tls-between-components.md) + + [生成自签名证书](/generate-self-signed-certificates.md) + + 权限 + + [与 MySQL 安全特性差异](/security-compatibility-with-mysql.md) + + [权限管理](/privilege-management.md) + + [TiDB 用户账户管理](/user-account-management.md) + + [基于角色的访问控制](/role-based-access-control.md) + + [TiDB 证书鉴权使用指南](/certificate-authentication.md) +>>>>>>> a4c0315... *: replace black-white-list by table filter (#3916) + SQL - [与 MySQL 兼容性对比](/mysql-compatibility.md) + SQL 语言结构 diff --git a/br/backup-and-restore-tool.md b/br/backup-and-restore-tool.md new file mode 100644 index 000000000000..94148ed7af35 --- /dev/null +++ b/br/backup-and-restore-tool.md @@ -0,0 +1,575 @@ +--- +title: 使用 BR 进行备份与恢复 +summary: 了解如何使用 BR 工具进行集群数据备份和恢复。 +category: how-to +aliases: ['/docs-cn/dev/reference/tools/br/br/','/docs-cn/dev/how-to/maintain/backup-and-restore/br/'] +--- + +# 使用 BR 进行备份与恢复 + +Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`mydumper`/`loader`](/backup-and-restore-using-mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。 + +## 使用限制 + +- BR 只支持 TiDB v3.1 及以上版本。 +- 目前只支持在全新的集群上执行恢复操作。 +- BR 备份最好串行执行，否则不同备份任务之间会相互影响。 +- BR 只支持在 `new_collations_enabled_on_first_bootstrap` [开关值](/character-set-and-collation.md#排序规则支持)相同的集群之间进行操作。这是因为 BR 仅备份 KV 数据。如果备份集群和恢复集群采用不同的排序规则，数据校验会不通过。所以恢复集群时，你需要确保 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME='new_collation_enabled';` 语句的开关值查询结果与备份时的查询结果相一致，才可以进行恢复。 + + - 对于 v3.1 集群，TiDB 尚未支持 new collation，因此可以认为 new collation 未打开 + - 对于 v4.0 集群，请通过 `SELECT VARIABLE_VALUE FROM mysql.tidb WHERE VARIABLE_NAME='new_collation_enabled';` 查看 new collation 是否打开。 + + 例如，数据备份在 v3.1 集群。如果恢复到 v4.0 集群中，查询恢复集群的 `new_collation_enabled` 的值为 `true`，则说明创建恢复集群时打开了 new collation 支持的开关。此时恢复数据，可能会出错。 + +## 推荐部署配置 + +- 推荐 BR 部署在 PD 节点上。 +- 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。 + +## 下载 Binary + +详见[下载链接](/download-ecosystem-tools.md#快速备份和恢复br)。 + +## 工作原理 + +BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。更多信息请参阅[备份恢复设计方案](https://github.com/pingcap/br/blob/980627aa90e5d6f0349b423127e0221b4fa09ba0/docs/cn/2019-08-05-new-design-of-backup-restore.md) + +![br-arch](/media/br-arch.png) + +### 备份文件类型 + +备份路径下会生成以下两种类型文件： + +- SST 文件：存储 TiKV 备份下来的数据信息 +- `backupmeta` 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值 + +### SST 文件命名格式 + +SST 文件以 `storeID_regionID_regionEpoch_keyHash_cf` 的格式命名。格式名的解释如下： + +- storeID：TiKV 节点编号 +- regionID：Region 编号 +- regionEpoch：Region 版本号 +- keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性 +- cf：RocksDB 的 ColumnFamily（默认为 `default` 或 `write`） + +## BR 命令行描述 + +一条 `br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。 + +以下是一条完整的 `br` 命令行： + +`br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"` + +命令行各部分的解释如下： + +* `backup`：`br` 的子命令 +* `full`：`backup` 的子命令 +* `-s` 或 `--storage`：备份保存的路径 +* `"local:///tmp/backup"`：`-s` 的参数，保存的路径为各个 TiKV 节点本地磁盘的 `/tmp/backup` +* `--pd`：PD 服务地址 +* `"${PDIP}:2379"`：`--pd` 的参数 + +> **注意：** +> +> 在使用 `local` storage 的时候，备份数据会分散在各个节点的本地文件系统中。 +> +> **不建议**在生产环境中备份到本地磁盘，因为在日后恢复的时候，**必须**手动聚集这些数据才能完成恢复工作（见[恢复集群数据](#恢复集群数据)）。 +> +> 聚集这些备份数据可能会造成数据冗余和运维上的麻烦，而且在不聚集这些数据便直接恢复的时候会遇到颇为迷惑的 `SST file not found` 报错。 +> +> 建议在各个节点挂载 NFS 网盘，或者直接备份到 `S3` 对象存储中。 + +### 命令和子命令 + +BR 由多层命令组成。目前，BR 包含 `backup`、`restore` 和 `version` 三个子命令: + +* `br backup` 用于备份 TiDB 集群 +* `br restore` 用于恢复 TiDB 集群 +* `br version` 用于查看 BR 工具版本信息 + +以上三个子命令可能还包含这些子命令： + +* `full`：可用于备份或恢复全部数据。 +* `db`：可用于备份或恢复集群中的指定数据库。 +* `table`：可用于备份或恢复集群指定数据库中的单张表。 + +### 常用选项 + +* `--pd`：用于连接的选项，表示 PD 服务地址，例如 `"${PDIP}:2379"`。 +* `-h`/`--help`：获取所有命令和子命令的使用帮助。例如 `br backup --help`。 +* `--ca`：指定 PEM 格式的受信任 CA 的证书文件路径。 +* `--cert`：指定 PEM 格式的 SSL 证书文件路径。 +* `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 +* `--status-addr`：BR 向 Prometheus 提供统计数据的监听地址。 + +## 备份集群数据 + +使用 `br backup` 命令来备份集群数据。可选择添加 `full` 或 `table` 子命令来指定备份的范围：全部集群数据或单张表的数据。 + +如果备份时间可能超过设定的 [`tikv_gc_life_time`](/garbage-collection-configuration.md#tikv_gc_life_time)（默认 `10m0s`，即表示 10 分钟），则需要将该参数调大。 + +例如，将 `tikv_gc_life_time` 调整为 `720h`： + +{{< copyable "sql" >}} + +```sql +mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \ + "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'"; +``` + +### 备份全部集群数据 + +要备份全部集群数据，可使用 `br backup full` 命令。该命令的使用帮助可以通过 `br backup full -h` 或 `br backup full --help` 来获取。 + +用例：将所有集群数据备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +> **注意：** +> +> + 经测试，在全速备份的情况下，如果备份盘和服务盘不同，在线备份会让只读线上服务的 QPS 下降 15%~25% 左右。如果希望降低影响，请参考 `--ratelimit` 进行限速。 +> + 假如备份盘和服务盘相同，备份将会和服务争夺 I/O 资源，这可能会让只读线上服务的 QPS 骤降一半以上。请尽量禁止将在线服务的数据备份到 TiKV 的数据盘。 + +{{< copyable "shell-regular" >}} + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --log-file backupfull.log +``` + +以上命令中，`--ratelimit` 选项限制了**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）。`--log-file` 选项指定把 BR 的 log 写到 `backupfull.log` 文件中。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下： + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --log-file backupfull.log +Full Backup <---------/................................................> 17.12%. +``` + +### 备份单个数据库的数据 + +要备份集群中指定单个数据库的数据，可使用 `br backup db` 命令。同样可通过 `br backup db -h` 或 `br backup db --help` 来获取子命令 `db` 的使用帮助。 + +用例：将数据库 `test` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +{{< copyable "shell-regular" >}} + +```shell +br backup db \ + --pd "${PDIP}:2379" \ + --db test \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --log-file backuptable.log +``` + +`db` 子命令的选项为 `--db`，用来指定数据库名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 + +### 备份单张表的数据 + +要备份集群中指定单张表的数据，可使用 `br backup table` 命令。同样可通过 `br backup table -h` 或 `br backup table --help` 来获取子命令 `table` 的使用帮助。 + +用例：将表 `test.usertable` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 + +{{< copyable "shell-regular" >}} + +```shell +br backup table \ + --pd "${PDIP}:2379" \ + --db test \ + --table usertable \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --log-file backuptable.log +``` + +`table` 子命令有 `--db` 和 `--table` 两个选项，分别用来指定数据库名和表名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 + +备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 + +### 使用表库过滤功能备份多张表的数据 + +如果你需要以更复杂的过滤条件来备份多个表，执行 `br backup full` 命令，并使用 `--filter` 或 `-f` 来指定[表库过滤](/table-filter.md)规则。 + +用例：以下命令将所有 `db*.tbl*` 形式的表格数据备份到每个 TiKV 节点上的 `/tmp/backup` 路径，并将 `backupmeta` 文件写入该路径。 + +{{< copyable "shell-regular" >}} + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --filter 'db*.tbl*' \ + --storage "local:///tmp/backup" \ + --ratelimit 120 \ + --log-file backupfull.log +``` + +### 备份数据到 Amazon S3 后端存储 + +如果备份的存储并不是在本地，而是在 Amazon 的 S3 后端存储，那么需要在 `storage` 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。 + +这里可以参照 [AWS 官方文档](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/user-guide/create-bucket.html)在指定的 `Region` 区域中创建一个 S3 桶 `Bucket`，如果有需要，还可以参照 [AWS 官方文档](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/user-guide/create-folder.html) 在 Bucket 中创建一个文件夹 `Folder`。 + +将有权限访问该 S3 后端存储的账号的 `SecretKey` 和 `AccessKey` 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。 + +{{< copyable "shell-regular" >}} + +```shell +export AWS_ACCESS_KEY_ID=${AccessKey} +export AWS_SECRET_ACCESS_KEY=${SecretKey} +``` + +在进行 BR 备份时，显示指定参数 `--s3.region` 和 `--send-credentials-to-tikv`, `--s3.region` 表示 S3 存储所在的区域，`--send-credentials-to-tikv` 表示将 S3 的访问权限传递给 TiKV 节点。 + +{{< copyable "shell-regular" >}} + +```shell +br backup full \ + --pd "${PDIP}:2379" \ + --storage "s3://${Bucket}/${Folder}" \ + --s3.region "${region}" \ + --send-credentials-to-tikv true \ + --log-file backuptable.log +``` + +### 增量备份 + +如果想要备份增量，只需要在备份的时候指定**上一次的备份时间戳** `--lastbackupts` 即可。 + +注意增量备份有以下限制： + +- 增量备份需要与前一次全量备份在不同的路径下 +- GC safepoint 必须在 `lastbackupts` 之前 + +{{< copyable "shell-regular" >}} + +```shell +br backup full\ + --pd ${PDIP}:2379 \ + -s local:///home/tidb/backupdata/incr \ + --lastbackupts ${LAST_BACKUP_TS} +``` + +以上命令会备份 `(LAST_BACKUP_TS, current PD timestamp]` 之间的增量数据。 + +你可以使用 `validate` 指令获取上一次备份的时间戳，示例如下： + +{{< copyable "shell-regular" >}} + +```shell +LAST_BACKUP_TS=`br validate decode --field="end-version" -s local:///home/tidb/backupdata` +``` + +示例备份的增量数据包括 `(LAST_BACKUP_TS, current PD timestamp]` 之间的新写入数据，以及这段时间内的 DDL。在恢复的时候，BR 会先把所有 DDL 恢复，而后才会恢复写入数据。 + +### Raw KV 备份（实验性功能） + +> **警告：** +> +> Raw KV 备份功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。 + +在某些使用场景下，TiKV 可能会独立于 TiDB 运行。考虑到这点，BR 也提供跳过 TiDB 层，直接备份 TiKV 中数据的功能： + +{{< copyable "shell-regular" >}} + +```shell +br backup raw --pd $PD_ADDR \ + -s "local://$BACKUP_DIR" \ + --start 31 \ + --end 3130303030303030 \ + --format hex \ + --cf default +``` + +以上命令会备份 default CF 上 `[0x31, 0x3130303030303030)` 之间的所有键到 `$BACKUP_DIR` 去。 + +这里，`--start` 和 `--end` 的参数会先依照 `--format` 指定的方式解码，再被送到 TiKV 上去，目前支持以下解码方式： + +- "raw"：不进行任何操作，将输入的字符串直接编码为二进制格式的键。 +- "hex"：将输入的字符串视作十六进制数字。这是默认的编码方式。 +- "escape"：对输入的字符串进行转义之后，再编码为二进制格式。 + +## 恢复集群数据 + +使用 `br restore` 命令来恢复备份数据。可选择添加 `full`、`db` 或 `table` 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。 + +> **注意：** +> +> 如果使用本地存储，在恢复前**必须**将所有备份的 SST 文件复制到各个 TiKV 节点上 `--storage` 指定的目录下。 +> +> 即使每个 TiKV 节点最后只需要读取部分 SST 文件，这些节点也需要有所有 SST 文件的完全访问权限。原因如下： +> +> * 数据被复制到了多个 Peer 中。在读取 SST 文件时，这些文件必须要存在于所有 Peer 中。这与数据的备份不同，在备份时，只需从单个节点读取。 +> * 在数据恢复的时候，每个 Peer 分布的位置是随机的，事先并不知道哪个节点将读取哪个文件。 +> +> 使用共享存储可以避免这些情况。例如，在本地路径上安装 NFS，或使用 S3。利用这些网络存储，各个节点都可以自动读取每个 SST 文件，此时上述注意事项不再适用。 + +### 恢复全部备份数据 + +要将全部备份数据恢复到集群中来，可使用 `br restore full` 命令。该命令的使用帮助可以通过 `br restore full -h` 或 `br restore full --help` 来获取。 + +用例：将 `/tmp/backup` 路径中的全部备份数据恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --ratelimit 128 \ + --log-file restorefull.log +``` + +以上命令中，`--ratelimit` 选项限制了**每个 TiKV** 执行恢复任务的速度上限（单位 MiB/s）。`--log-file` 选项指定把 BR 的 log 写到 `restorefull.log` 文件中。 + +恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下： + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +Full Restore <---------/...............................................> 17.12%. +``` + +### 恢复单个数据库的数据 + +要将备份数据中的某个数据库恢复到集群中，可以使用 `br restore db` 命令。该命令的使用帮助可以通过 `br restore db -h` 或 `br restore db --help` 来获取。 + +用例：将 `/tmp/backup` 路径中备份数据中的某个数据库恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore db \ + --pd "${PDIP}:2379" \ + --db "test" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +``` + +以上命令中 `--db` 选项指定了需要恢复的数据库名字。其余选项的含义与[恢复全部备份数据](#恢复全部备份数据)相同。 + +### 恢复单张表的数据 + +要将备份数据中的某张数据表恢复到集群中，可以使用 `br restore table` 命令。该命令的使用帮助可通过 `br restore table -h` 或 `br restore table --help` 来获取。 + +用例：将 `/tmp/backup` 路径下的备份数据中的某个数据表恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore table \ + --pd "${PDIP}:2379" \ + --db "test" \ + --table "usertable" \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +``` + +### 使用表库功能过滤恢复数据 + +如果你需要用复杂的过滤条件来恢复多个表，执行 `br restore full` 命令，并用 `--filter` 或 `-f` 指定使用[表库过滤](/table-filter.md)。 + +用例：以下命令将备份在 `/tmp/backup` 路径的表的子集恢复到集群中。 + +{{< copyable "shell-regular" >}} + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --filter 'db*.tbl*' \ + --storage "local:///tmp/backup" \ + --log-file restorefull.log +``` + +### 从 Amazon S3 后端存储恢复数据 + +如果需要恢复的数据并不是存储在本地，而是在 Amazon 的 S3 后端，那么需要在 `storage` 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。 + +将有权限访问该 S3 后端存储的账号的 `SecretKey` 和 `AccessKey` 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。 + +{{< copyable "shell-regular" >}} + +```shell +export AWS_ACCESS_KEY_ID=${AccessKey} +export AWS_SECRET_ACCESS_KEY=${SecretKey} +``` + +在进行 BR 恢复时，显示指定参数 `--s3.region` 和 `--send-credentials-to-tikv`, `--s3.region` 表示 S3 存储所在的区域，`--send-credentials-to-tikv` 表示将 S3 的访问权限传递给 TiKV 节点。`--storage`参数中的 `Bucket` 和 `Folder` 分别代表需要恢复的数据所在的 S3 存储桶和文件夹。 + +{{< copyable "shell-regular" >}} + +```shell +br restore full \ + --pd "${PDIP}:2379" \ + --storage "s3://${Bucket}/${Folder}" \ + --s3.region "${region}" \ + --send-credentials-to-tikv=true \ + --log-file restorefull.log +``` + +以上命令中 `--table` 选项指定了需要恢复的表名。其余选项的含义与[恢复单个数据库](#恢复单个数据库的数据)相同。 + +### 增量恢复 + +增量恢复的方法和使用 BR 进行全量恢复的方法并无差别。需要注意，恢复增量数据的时候，需要保证备份时指定的 `last backup ts` 之前备份的数据已经全部恢复到目标集群。 + +### Raw KV 恢复（实验性功能） + +> **警告：** +> +> Raw KV 恢复功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。 + +和 [Raw KV 备份](#raw-kv-备份实验性功能)相似地，恢复 Raw KV 的命令如下： + +{{< copyable "shell-regular" >}} + +```shell +br restore raw --pd $PD_ADDR \ + -s "local://$BACKUP_DIR" \ + --start 31 \ + --end 3130303030303030 \ + --format hex \ + --cf default +``` + +以上命令会将范围在 `[0x31, 0x3130303030303030)` 的已备份键恢复到 TiKV 集群中。这里键的编码方式和备份时相同。 + +### 在线恢复（实验性功能） + +> **警告：** +> +> 在线恢复功能还在实验中，没有经过完备的测试，同时还依赖 PD 的不稳定特性 Placement Rules。暂时请避免在生产环境中使用该功能。 + +在恢复的时候，写入过多的数据会影响在线集群的性能。为了尽量避免影响线上业务，BR 支持通过 [Placement rules](/configure-placement-rules.md) 隔离资源。让下载、导入 SST 的工作仅仅在指定的几个节点（下称“恢复节点”）上进行，具体操作如下： + +1. 配置 PD，启动 Placement rules： + + {{< copyable "shell-regular" >}} + + ```shell + echo "config set enable-placement-rules true" | pd-ctl + ``` + +2. 编辑恢复节点 TiKV 的配置文件，在 `server` 一项中指定： + + {{< copyable "" >}} + + ``` + [server] + labels = { exclusive = "restore" } + ``` + +3. 启动恢复节点的 TiKV，使用 BR 恢复备份的文件，和非在线恢复相比，这里只需要加上 `--online` 标志即可： + + {{< copyable "shell-regular" >}} + + ``` + br restore full \ + -s "local://$BACKUP_DIR" \ + --pd $PD_ADDR \ + --online + ``` + +## 最佳实践 + +- 推荐在 `-s` 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。 +- 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。 +- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。 + +更多最佳实践内容，参见 [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md)。 + +## 备份和恢复示例 + +本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。 + +### 数据规模和机器配置 + +假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。 + +```sql +MySQL [sbtest]> show tables; ++------------------+ +| Tables_in_sbtest | ++------------------+ +| sbtest1 | +| sbtest10 | +| sbtest2 | +| sbtest3 | +| sbtest4 | +| sbtest5 | +| sbtest6 | +| sbtest7 | +| sbtest8 | +| sbtest9 | ++------------------+ + +MySQL [sbtest]> select count(*) from sbtest1; ++----------+ +| count(*) | ++----------+ +| 5000000 | ++----------+ +1 row in set (1.04 sec) +``` + +表结构如下： + +```sql +CREATE TABLE `sbtest1` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `k` int(11) NOT NULL DEFAULT '0', + `c` char(120) NOT NULL DEFAULT '', + `pad` char(60) NOT NULL DEFAULT '', + PRIMARY KEY (`id`), + KEY `k_1` (`k`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499 +``` + +示例假设有 4 个 TiKV 节点，每个节点配置如下： + +| CPU | 内存 | 磁盘 | 副本数 | +| :--- | :--- | :--- | :--- | +| 16 核 | 32 GB | SSD | 3 | + +### 备份示例 + +- 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断 +- 备份前需确认 TiDB 集群没有执行 DDL 操作 + +执行以下命令对集群中的全部数据进行备份： + +{{< copyable "shell-regular" >}} + +``` +bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log +``` + +``` +[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs] +``` + +### 恢复示例 + +恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。 + +执行以下命令对全部数据进行恢复： + +{{< copyable "shell-regular" >}} + +``` +bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log +``` + +``` +[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms] +``` diff --git a/export-or-backup-using-dumpling.md b/export-or-backup-using-dumpling.md index 01cc4292fd31..78994f524a15 100644 --- a/export-or-backup-using-dumpling.md +++ b/export-or-backup-using-dumpling.md @@ -80,7 +80,7 @@ dumpling \ #### 使用 `--filter` 指令筛选数据 -Dumpling 可以通过 `--filter` 指定 table-filter 来筛选特定的库表。table-filter 的语法与 .gitignore 相似，[详细语法参考](https://github.com/pingcap/tidb-tools/blob/master/pkg/table-filter/README.md)。 +Dumpling 可以通过 `--filter` 指定 table-filter 来筛选特定的库表。table-filter 的语法与 .gitignore 相似，详细语法参考[表库过滤](/table-filter.md)。 {{< copyable "shell-regular" >}} diff --git a/table-filter.md b/table-filter.md new file mode 100644 index 000000000000..a80728bf652b --- /dev/null +++ b/table-filter.md @@ -0,0 +1,251 @@ +--- +title: 表库过滤 +summary: 在 TiDB 生态工具中使用表库过滤功能。 +aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-table-filter/','/docs-cn/dev/reference/tools/tidb-lightning/table-filter/','/zh/tidb/dev/tidb-lightning-table-filter/'] +--- + +# 表库过滤 + +TiDB 生态工具默认情况下作用于所有数据库，但实际使用中，往往只需要作用于其中的部分子集。例如，用户只想处理 `foo*` 和 `bar*` 形式的表，而无需对其他表进行操作。 + +从 TiDB 4.0 起，所有 TiDB 生态系统工具都使用一个通用的过滤语法来定义子集。本文档介绍如何使用表库过滤功能。 + +## 使用表库过滤 + +### 命令行 + +在命令行中使用多个 `-f` 或 `--filter` 参数，即可在 TiDB 生态工具中应用表库过滤规则。每个过滤规则均采用 `db.table` 形式，支持通配符（详情见[下一节](#使用通配符)）。以下为各个工具中的使用示例： + +* [BR](/br/backup-and-restore-tool.md)： + + {{< copyable "shell-regular" >}} + + ```shell + ./br backup full -f 'foo*.*' -f 'bar*.*' -s 'local:///tmp/backup' + # ^~~~~~~~~~~~~~~~~~~~~~~ + ./br restore full -f 'foo*.*' -f 'bar*.*' -s 'local:///tmp/backup' + # ^~~~~~~~~~~~~~~~~~~~~~~ + ``` + +* [Dumpling](/backup-and-restore-using-dumpling-lightning.md)： + + {{< copyable "shell-regular" >}} + + ```shell + ./dumpling -f 'foo*.*' -f 'bar*.*' -P 3306 -o /tmp/data/ + # ^~~~~~~~~~~~~~~~~~~~~~~ + ``` + +* [Lightning](/tidb-lightning/tidb-lightning-overview.md)： + + {{< copyable "shell-regular" >}} + + ```shell + ./tidb-lightning -f 'foo*.*' -f 'bar*.*' -d /tmp/data/ --backend tidb + # ^~~~~~~~~~~~~~~~~~~~~~~ + ``` + +### TOML 配置文件 + +在 TOML 文件中，表库过滤规则以[字符串数组](https://toml.io/cn/v1.0.0-rc.1#%E6%95%B0%E7%BB%84)的形式指定。以下为各个工具中的使用示例： + +* Lightning： + + ```toml + [mydumper] + filter = ['foo*.*', 'bar*.*'] + ``` + +* [TiCDC](/ticdc/ticdc-overview.md)： + + ```toml + [filter] + rules = ['foo*.*', 'bar*.*'] + + [[sink.dispatchers]] + matcher = ['db1.*', 'db2.*', 'db3.*'] + dispatcher = 'ts' + ``` + +## 表库过滤语法 + +### 直接使用表名 + +每条表库过滤规则由“库”和“表”组成，两部分之间以英文句号 (`.`) 分隔。只有表名与规则完全相符的表才会被接受。 + +``` +db1.tbl1 +db2.tbl2 +db3.tbl3 +``` + +表名只由有效的[标识符](/schema-object-names.md)组成，例如： + +* 数字（`0` 到 `9`） +* 字母（`a` 到 `z`，`A` 到 `Z`） +* `$` +* `_` +* 非 ASCII 字符（`U+0080` 到 `U+10FFFF`） + +其他 ASCII 字符均为保留字。部分标点符号有特殊含义，详情见下一节。 + +### 使用通配符 + +表名的两个部分均支持使用通配符（详情见 [fnmatch(3)](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13)）。 + +* `*`：匹配零个或多个字符。 +* `?`：匹配一个字符。 +* `[a-z]`：匹配 “a” 和 “z” 之间的一个字符。 +* `[!a-z]`：匹配不在 “a” 和 “z” 之间的一个字符。 + +``` +db[0-9].tbl[0-9a-f][0-9a-f] +data.* +*.backup_* +``` + +此处，“字符”指的是一个 Unicode 码位，例如： + +* `U+00E9` (é) 是 1 个字符。 +* `U+0065 U+0301` (é) 是 2 个字符。 +* `U+1F926 U+1F3FF U+200D U+2640 U+FE0F` (🤦🏿‍♀️) 是 5 个字符。 + +### 使用文件导入 + +如需导入一个文件作为过滤规则，请在规则的开头加上一个 “@” 来指定文件名。库表过滤解析器将导入文件中的每一行都解析为一条额外的过滤规则。 + +例如，`config/filter.txt` 文件有以下内容： + +``` +employees.* +*.WorkOrder +``` + +以下两条表库过滤命令是等价的： + +```bash +./dumpling -f '@config/filter.txt' +./dumpling -f 'employees.*' -f '*.WorkOrder' +``` + +导入的文件里不能使用过滤规则导入另一个文件。 + +### 注释与空行 + +导入的过滤规则文件中，每一行开头和结尾的空格都会被去除。此外，空行（空字符串）也将被忽略。 + +行首的 `#` 表示该行是注释，会被忽略。而不在行首的 `#` 则会被认为是语法错误。 + +``` +# 这是一行注释 +db.table # 这一部分不是注释，且可能引起错误 +``` + +### 排除规则 + +在一条过滤规则的开头加上 `!`，则表示符合这条规则的表不会被 TiDB 生态工具处理。通过应用排除规则，库表过滤可以作为屏蔽名单来使用。 + +``` +*.* +#^ 注意：必须先添加 *.* 规则来包括所有表 +!*.Password +!employees.salaries +``` + +### 转义字符 + +如果需要将特殊字符转化为标识符，可以在特殊字符前加上反斜杠 `\`。 + +``` +db\.with\.dots.* +``` + +为了简化语法并向上兼容，**不支持**下列字符序列： + +- 在行尾去除空格后使用 `\`（使用 `[ ]` 来匹配行尾的空格）。 +- 在 `\` 后使用数字或字母 (`[0-9a-zA-Z]`)。特别是类似 C 的转义序列，如 `\0`、`\r`、`\n`、`\t` 等序列，目前在表库过滤规则中无意义。 + +### 引号包裹的标识符 + +除了 `\` 之外，还可以用 `"` 和 `` ` `` 来控制特殊字符。 + +``` +"db.with.dots"."tbl\1" +`db.with.dots`.`tbl\2` +``` + +也可以通过输入两次引号，将引号包含在标识符内。 + +``` +"foo""bar".`foo``bar` +# 等价于： +foo\"bar.foo\`bar +``` + +用引号包裹的标识符不可以跨越多行。 + +用引号只包裹标识符的一部分是无效的，例如： + +``` +"this is "invalid*.* +``` + +### 正则表达式 + +如果你需要使用较复杂的过滤规则，可以将每个匹配模型写为正则表达式，以 `/` 为分隔符： + +``` +/^db\d{2,}$/./^tbl\d{2,}$/ +``` + +这类正则表示使用 [Go dialect](https://pkg.go.dev/regexp/syntax?tab=doc)。只要标识符中有一个子字符串与正则表达式匹配，则视为匹配该模型。例如，`/b/` 匹配 `db01`。 + +> **注意：** +> +> 正则表达式中的每一个 `/` 都需要转义为 `\/`，包括在 `[...]` 里面的 `/`。不允许在 `\Q...\E` 之间放置一个未转义的 `/`。 + +## 使用多个过滤规则 + +当表的名称与过滤列表中所有规则均不匹配时，默认情况下这些表被忽略。 + +要建立一个屏蔽名单，必须使用显式的 `*.*` 作为第一条过滤规则，否则所有表均被排除。 + +```bash +# 所有表均被过滤掉 +./dumpling -f '!*.Password' + +# 只有 “Password” 表被过滤掉，其余表仍保留 +./dumpling -f '*.*' -f '!*.Password' +``` + +如果一个表的名称与过滤列表中的多个规则匹配，则以最后匹配的规则为准。例如： + +``` +# rule 1 +employees.* +# rule 2 +!*.dep* +# rule 3 +*.departments +``` + +过滤结果如下： + +| 表名 | 规则 1 | 规则 2 | 规则 3 | 结果 | +|-----------------------|--------|--------|--------|------------------| +| irrelevant.table | | | | 默认（拒绝） | +| employees.employees | ✓ | | | 规则 1（接受） | +| employees.dept_emp | ✓ | ✓ | | 规则 2（拒绝） | +| employees.departments | ✓ | ✓ | ✓ | 规则 3（接受） | +| else.departments | | ✓ | ✓ | 规则 3（接受） | + +> **注意：** +> +> 在 TiDB 生态工具中，无论表库过滤如何设置，系统库总是被排除。系统库有以下六个： +> +> * `INFORMATION_SCHEMA` +> * `PERFORMANCE_SCHEMA` +> * `METRICS_SCHEMA` +> * `INSPECTION_SCHEMA` +> * `mysql` +> * `sys` diff --git a/ticdc/manage-ticdc.md b/ticdc/manage-ticdc.md new file mode 100644 index 000000000000..31e7d6fd521f --- /dev/null +++ b/ticdc/manage-ticdc.md @@ -0,0 +1,555 @@ +--- +title: TiCDC 运维操作及任务管理 +category: reference +aliases: ['/docs-cn/dev/reference/tools/ticdc/manage/','/docs-cn/dev/reference/tools/ticdc/sink/','/docs-cn/dev/ticdc/sink-url/'] +--- + +# TiCDC 运维操作及任务管理 + +本文档介绍如何部署 TiCDC 集群，以及如何通过 TiCDC 提供的命令行工具 `cdc cli` 和 HTTP 接口两种方式来管理 TiCDC 集群和同步任务。 + +## TiCDC 部署 + +### 软件和硬件环境推荐配置 + +在生产环境中，TiCDC 的软件和硬件配置推荐如下： + +| Linux 操作系统平台 | 版本 | +| :----------------------- | :----------: | +| Red Hat Enterprise Linux | 7.3 及以上 | +| CentOS | 7.3 及以上 | + +| **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | +| --- | --- | --- | --- | --- | +| 16 核+ | 64 GB+ | SSD | 万兆网卡（2 块最佳） | 2 | + +更多信息参见 [TiDB 软件和硬件环境建议配置](/hardware-and-software-requirements.md) + +### 使用 TiUP 部署 + +#### 使用 TiUP 部署包含 TiCDC 组件的 TiDB 集群 + +详细操作参考[使用 TiUP 部署 TiCDC](/production-deployment-using-tiup.md#第-3-步编辑初始化配置文件)。 + +#### 使用 TiUP 在原有 TiDB 集群上新增 TiCDC 组件 + +1. 首先确认当前 TiDB 的版本支持 TiCDC，否则需要先升级 TiDB 集群至 4.0.0 rc.1 或更新版本。 + +2. 参考 [扩容 TiDB/TiKV/PD/TiCDC 节点](/scale-tidb-using-tiup.md#扩容-ticdc-节点) 章节对 TiCDC 进行部署。 + +### 在原有 TiDB 集群上使用 binary 部署 TiCDC 组件 + +假设 PD 集群有一个可以提供服务的 PD 节点（client URL 为 `10.0.10.25:2379`）。若要部署三个 TiCDC 节点，可以按照以下命令启动集群。只需要指定相同的 PD 地址，新启动的节点就可以自动加入 TiCDC 集群。 + +{{< copyable "shell-regular" >}} + +```shell +cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_1.log --addr=0.0.0.0:8301 --advertise-addr=127.0.0.1:8301 +cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_2.log --addr=0.0.0.0:8302 --advertise-addr=127.0.0.1:8302 +cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_3.log --addr=0.0.0.0:8303 --advertise-addr=127.0.0.1:8303 +``` + +对于 `cdc server` 命令中可用选项解释如下： + +- `gc-ttl`: TiCDC 在 PD 设置的服务级别 GC safepoint 的 TTL (Time To Live) 时长，单位为秒，默认值为 `86400`，即 24 小时。 +- `pd`: PD client 的 URL。 +- `addr`: TiCDC 的监听地址，提供服务的 HTTP API 查询地址和 Prometheus 查询地址。 +- `advertise-addr`: TiCDC 对外访问地址。 +- `tz`: TiCDC 服务使用的时区。TiCDC 在内部转换 timestamp 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。 +- `log-file`: TiCDC 进程运行日志的地址，默认为 `cdc.log`。 +- `log-level`: TiCDC 进程运行时默认的日志级别，默认为 `info`。 + +## 使用 `cdc cli` 工具来管理集群状态和数据同步 + +以下内容介绍如何使用 `cdc cli` 工具来管理集群状态和数据同步。在以下接口描述中，假设 PD 的监听 IP 地址为 `10.0.10.25`，端口为 `2379`。 + +### 管理 TiCDC 服务进程 (`capture`) + +- 查询 `capture` 列表： + + {{< copyable "shell-regular" >}} + + ```shell + cdc cli capture list --pd=http://10.0.10.25:2379 + ``` + + ``` + [ + { + "id": "6d92386a-73fc-43f3-89de-4e337a42b766", + "is-owner": true + }, + { + "id": "b293999a-4168-4988-a4f4-35d9589b226b", + "is-owner": false + } + ] + ``` + +### 管理同步任务 (`changefeed`) + +#### 创建同步任务 + +使用以下命令来创建同步任务： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed create --pd=http://10.0.10.25:2379 --sink-uri="mysql://root:123456@127.0.0.1:3306/" +create changefeed ID: 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f info {"sink-uri":"mysql://root:123456@127.0.0.1:3306/","opts":{},"create-time":"2020-03-12T22:04:08.103600025+08:00","start-ts":415241823337054209,"target-ts":0,"admin-job-type":0,"config":{"filter-case-sensitive":false,"filter-rules":null,"ignore-txn-start-ts":null}} +``` + +其中 `--sink-uri` 需要按照以下格式进行配置，目前 scheme 支持 `mysql`/`tidb`/`kafka`。 + +{{< copyable "" >}} + +``` +[scheme]://[userinfo@][host]:[port][/path]?[query_parameters] +``` + +- Sink URI 配置 `mysql`/`tidb` + + 配置样例如下所示： + + {{< copyable "shell-regular" >}} + + ```shell + --sink-uri="mysql://root:123456@127.0.0.1:3306/?worker-count=16&max-txn-row=5000" + ``` + + 以上配置命令中的参数解析如下： + + | 参数 | 解析 | + | :------------ | :------------------------------------------------ | + | `root` | 下游数据库的用户名 | + | `123456` | 下游数据库密码 | + | `127.0.0.1` | 下游数据库的 IP | + | `3306` | 下游数据的连接端口 | + | `worker-count` | 向下游执行 SQL 的并发度（可选，默认值为 `16`） | + | `max-txn-row` | 向下游执行 SQL 的 batch 大小（可选，默认值为 `256`） | + +- Sink URI 配置 `kafka` + + 配置样例如下所示： + + {{< copyable "shell-regular" >}} + + ```shell + --sink-uri="kafka://127.0.0.1:9092/cdc-test?kafka-version=2.4.0&partition-num=6&max-message-bytes=67108864&replication-factor=1" + ``` + + 以上配置命令中的参数解析如下： + + | 参数 | 解析 | + | :------------------ | :------------------------------------------------------------ | + | `127.0.0.1` | 下游 Kafka 对外提供服务的 IP | + | `9092` | 下游 Kafka 的连接端口 | + | `cdc-test` | 使用的 Kafka topic 名字 | + | `kafka-version` | 下游 Kafka 版本号（可选，默认值 `2.4.0`） | + | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量。如果不填会自动获取 partition 数量。） | + | `max-message-bytes` | 每次向 Kafka broker 发送消息的最大数据量（可选，默认值 `64MB`） | + | `replication-factor` | kafka 消息保存副本数（可选，默认值 `1`） | + | `protocol` | 输出到 kafka 消息协议，可选值有 `default`, `canal`（默认值为 `default`） | + +如需设置更多同步任务的配置，比如指定同步单个数据表，请参阅[同步任务配置文件描述](#同步任务配置文件描述)。 + +使用配置文件创建同步任务的方法如下： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed create --pd=http://10.0.10.25:2379 --sink-uri="mysql://root:123456@127.0.0.1:3306/" --config changefeed.toml +``` + +其中 `changefeed.toml` 为同步任务的配置文件。 + +#### 查询同步任务列表 + +使用以下命令来查询同步任务列表： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed list --pd=http://10.0.10.25:2379 +``` + +``` +[ + { + "id": "28c43ffc-2316-4f4f-a70b-d1a7c59ba79f" + } +] +``` + +#### 查询特定同步任务 + +使用以下命令来查询特定同步任务（对应某个同步任务的信息和状态）： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed query --pd=http://10.0.10.25:2379 --changefeed-id=28c43ffc-2316-4f4f-a70b-d1a7c59ba79f +``` + +``` +{ + "info": { + "sink-uri": "mysql://root:123456@127.0.0.1:3306/", + "opts": {}, + "create-time": "2020-03-12T22:04:08.103600025+08:00", + "start-ts": 415241823337054209, + "target-ts": 0, + "admin-job-type": 0, + "config": { + "filter-case-sensitive": false, + "filter-rules": null, + "ignore-txn-start-ts": null + } + }, + "status": { + "resolved-ts": 415241860902289409, + "checkpoint-ts": 415241860640145409, + "admin-job-type": 0 + } +} +``` + +以上命令中： + +- `resolved-ts` 代表当前 changefeed 中最大的已经成功从 TiKV 发送到 TiCDC 的事务 TS； +- `checkpoint-ts` 代表当前 changefeed 中最大的已经成功写入下游的事务 TS； +- `admin-job-type` 代表一个 changefeed 的状态： + - `0`: 状态正常，也是初始状态。 + - `1`: 任务暂停。停止任务后所有同步 `processor` 会结束退出，同步任务的配置和同步状态都会保留，可以从 `checkpoint-ts` 恢复任务。 + - `2`: 任务恢复，同步任务从 `checkpoint-ts` 继续同步。 + - `3`: 任务已删除，接口请求后会结束所有同步 `processor`，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。 + +### 停止同步任务 + +使用以下命令来停止同步任务： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed pause --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f +``` + +以上命令中： + +- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 + +### 恢复同步任务 + +使用以下命令恢复同步任务： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed resume --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f +``` + +以上命令中： + +- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 + +### 删除同步任务 + +使用以下命令删除同步任务： + +{{< copyable "shell-regular" >}} + +```shell +cdc cli changefeed remove --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f +``` + +- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 + +### 管理同步子任务处理单元 (`processor`) + +- 查询 `processor` 列表： + + {{< copyable "shell-regular" >}} + + ```shell + cdc cli processor list --pd=http://10.0.10.25:2379 + ``` + + ``` + [ + { + "id": "9f84ff74-abf9-407f-a6e2-56aa35b33888", + "capture-id": "b293999a-4168-4988-a4f4-35d9589b226b", + "changefeed-id": "28c43ffc-2316-4f4f-a70b-d1a7c59ba79f" + } + ] + ``` + +- 查询特定 `processor`，对应于某个节点处理的同步子任务信息和状态： + + {{< copyable "shell-regular" >}} + + ```shell + cdc cli processor query --pd=http://10.0.10.25:2379 --changefeed-id=28c43ffc-2316-4f4f-a70b-d1a7c59ba79f --capture-id=b293999a-4168-4988-a4f4-35d9589b226b + ``` + + ``` + { + "status": { + "tables": { + "56": { # 56 表示同步表 id，对应 TiDB 中表的 tidb_table_id + "start-ts": 417474117955485702, + "mark-table-id": 0 # mark-table-id 是用于环形复制时标记表的 id，对应于 TiDB 中标记表的 tidb_table_id + } + }, + "operation": null, + "admin-job-type": 0 + }, + "position": { + "checkpoint-ts": 417474143881789441, + "resolved-ts": 417474143881789441, + "count": 0 + } + } + ``` + +以上命令中： + +- `status.tables` 中每一个作为 key 的数字代表同步表的 id，对应 TiDB 中表的 tidb_table_id； +- `mark-table-id` 是用于环形复制时标记表的 id，对应于 TiDB 中标记表的 tidb_table_id； +- `resolved-ts` 代表当前 processor 中已经排序数据的最大 TSO； +- `checkpoint-ts` 代表当前 processor 已经成功写入下游的事务的最大 TSO； + +## 使用 HTTP 接口管理集群状态和数据同步 + +目前 HTTP 接口提供一些基础的查询和运维功能。在以下接口描述中，假设 TiCDC server 的监听 IP 地址为 `127.0.0.1`，端口为 `8300`（在启动 TiCDC server 时通过 `--addr=ip:port` 指定绑定的 IP 和端口）。 + +### 获取 TiCDC server 状态信息的接口 + +使用以下命令获取 CDC server 状态信息的接口： + +{{< copyable "shell-regular" >}} + +```shell +curl http://127.0.0.1:8300/status +``` + +``` +{ + "version": "0.0.1", + "git_hash": "863f8ea889b144244ff53593a45c47ad22d37396", + "id": "6d92386a-73fc-43f3-89de-4e337a42b766", # capture id + "pid": 12102 # cdc server pid +} +``` + +### 驱逐 owner 节点 + +{{< copyable "shell-regular" >}} + +```shell +curl -X POST http://127.0.0.1:8300/capture/owner/resign +``` + +以上命令仅对 owner 节点请求有效。 + +``` +{ + "status": true, + "message": "" +} +``` + +{{< copyable "shell-regular" >}} + +```shell +curl -X POST http://127.0.0.1:8301/capture/owner/resign +``` + +以上命令对非 owner 节点请求返回错误。 + +``` +election: not leader +``` + +### 手动调度表到其他节点 + +{{< copyable "shell-regular" >}} + +```shell +curl -X POST curl 127.0.0.1:8300/capture/owner/move_table -X POST -d 'cf-id=cf060953-036c-4f31-899f-5afa0ad0c2f9&target-cp-id=6f19a6d9-0f8c-4dc9-b299-3ba7c0f216f5&table-id=49' +``` + +参数说明 + +| 参数名 | 说明 | +| :----------- | :--- | +| `cf-id` | 进行调度的 Changefeed ID | +| `target-cp-id` | 目标 Capture ID | +| `table-id` | 需要调度的 Table ID | + +以上命令仅对 owner 节点请求有效。对非 owner 节点将会返回错误。 + +``` +{ + "status": true, + "message": "" +} +``` + +## 同步任务配置文件描述 + +以下内容详细介绍了同步任务的配置。 + +```toml +# 指定配置文件中涉及的库名、表名是否为大小写敏感 +# 该配置会同时影响 filter 和 sink 相关配置，默认为 true +case-sensitive = true + +[filter] +# 忽略指定 start_ts 的事务 +ignore-txn-start-ts = [1, 2] + +# 过滤器规则 +# 过滤规则语法：https://github.com/pingcap/tidb-tools/tree/master/pkg/table-filter#syntax +rules = ['*.*', '!test.*'] + +[mounter] +# mounter 线程数，用于解码 TiKV 输出的数据 +worker-num = 16 + +[sink] +# 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器 +# 支持 default、ts、rowid、table 四种分发器 +dispatchers = [ + {matcher = ['test1.*', 'test2.*'], dispatcher = "ts"}, + {matcher = ['test3.*', 'test4.*'], dispatcher = "rowid"}, +] +# 对于 MQ 类的 Sink，可以指定消息的协议格式 +# 目前支持 default 和 canal 两种协议。default 为 TiCDC Open Protocol +protocol = "default" + +[cyclic-replication] +# 是否开启环形同步 +enable = false +# 当前 TiCDC 的复制 ID +replica-id = 1 +# 需要过滤掉的同步 ID +filter-replica-ids = [2,3] +# 是否同步 DDL +sync-ddl = true +``` + +### 配置文件兼容性的注意事项 + +* TiCDC v4.0.0 中移除了 `ignore-txn-commit-ts`，添加了 `ignore-txn-start-ts`，使用 start_ts 过滤事务。 +* TiCDC v4.0.2 中移除了 `db-dbs`/`db-tables`/`ignore-dbs`/`ignore-tables`，添加了 `rules`，使用新版的数据库和数据表过滤规则，详细语法参考[表库过滤](/table-filter.md)。 + +## 环形同步 + +> **警告：** +> +> 目前环形同步属于实验特性，尚未经过完备的测试，不建议在生产环境中使用该功能。 + +环形同步功能支持在多个独立的 TiDB 集群间同步数据。比如有三个 TiDB 集群 A、B 和 C，它们都有一个数据表 `test.user_data`，并且各自对它有数据写入。环形同步功能可以将 A、B 和 C 对 `test.user_data` 的写入同步其它集群上，使三个集群上的 `test.user_data` 达到最终一致。 + +### 环形同步使用示例 + +在三个集群 A、B 和 C 上开启环形复制，其中 A 到 B 的同步使用两个 TiCDC。A 作为三个集群的 DDL 入口。 + +![TiCDC cyclic replication](/media/cdc-cyclic-replication.png) + +使用环形同步功能时，需要设置同步任务的创建参数： + ++ `--cyclic-replica-id`：用于指定为上游集群的写入指定来源 ID，需要确保每个集群 ID 的唯一性。 ++ `--cyclic-filter-replica-ids`：用于指定需要过滤的写入来源 ID，通常为下游集群的 ID。 ++ `--cyclic-sync-ddl`：用于指定是否同步 DDL 到下游，只能在一个集群的 CDC 上开启 DDL 同步。 + +环形同步任务创建步骤如下： + +1. 在 TiDB 集群 A，B 和 C 上[启动 TiCDC 组件](#ticdc-部署)。 + + {{< copyable "shell-regular" >}} + + ```shell + # 在 TiDB 集群 A 上启动 TiCDC 组件。 + cdc server \ + --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ + --log-file=ticdc_1.log \ + --addr=0.0.0.0:8301 \ + --advertise-addr=127.0.0.1:8301 + + # 在 TiDB 集群 B 上启动 TiCDC 组件。 + cdc server \ + --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ + --log-file=ticdc_2.log \ + --addr=0.0.0.0:8301 \ + --advertise-addr=127.0.0.1:8301 + + # 在 TiDB 集群 C 上启动 TiCDC 组件。 + cdc server \ + --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ + --log-file=ticdc_3.log \ + --addr=0.0.0.0:8301 \ + --advertise-addr=127.0.0.1:8301 + ``` + +2. 在 TiDB 集群 A，B 和 C 上创建环形同步需要使用的标记数据表 (`mark table`)。 + + {{< copyable "shell-regular" >}} + + ```shell + # 在 TiDB 集群 A 上创建标记数据表。 + cdc cli changefeed cyclic create-marktables \ + --cyclic-upstream-dsn="root@tcp(${TIDB_A_HOST}:${TIDB_A_PORT})/" \ + --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ + + # 在 TiDB 集群 B 上创建标记数据表。 + cdc cli changefeed cyclic create-marktables \ + --cyclic-upstream-dsn="root@tcp(${TIDB_B_HOST}:${TIDB_B_PORT})/" \ + --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ + + # 在 TiDB 集群 C 上创建标记数据表。 + cdc cli changefeed cyclic create-marktables \ + --cyclic-upstream-dsn="root@tcp(${TIDB_C_HOST}:${TIDB_C_PORT})/" \ + --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ + ``` + +3. 在 TiDB 集群 A，B 和 C 上创建环形同步任务。 + + {{< copyable "shell-regular" >}} + + ```shell + # 在 TiDB 集群 A 上创建环形同步任务。 + cdc cli changefeed create \ + --sink-uri="mysql://root@${TiDB_B_HOST}/" \ + --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ + --cyclic-replica-id 1 \ + --cyclic-filter-replica-ids 2 \ + --cyclic-sync-ddl true + + # 在 TiDB 集群 B 上创建环形同步任务。 + cdc cli changefeed create \ + --sink-uri="mysql://root@${TiDB_C_HOST}/" \ + --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ + --cyclic-replica-id 2 \ + --cyclic-filter-replica-ids 3 \ + --cyclic-sync-ddl true + + # 在 TiDB 集群 C 上创建环形同步任务。 + cdc cli changefeed create \ + --sink-uri="mysql://root@${TiDB_A_HOST}/" \ + --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ + --cyclic-replica-id 3 \ + --cyclic-filter-replica-ids 1 \ + --cyclic-sync-ddl false + ``` + +### 环形同步使用限制 + +1. 在创建环形同步任务前，必须使用 `cdc cli changefeed cyclic create-marktables` 创建环形复制功能使用到的标记表。 +2. 开启环形复制的数据表只包含 [a-zA-z0-9_] 字符。 +3. 在创建环形同步任务前，开启环形复制的数据表必须已创建完毕。 +4. 开启环形复制后，不能创建一个会被环形同步任务同步的表。 +5. 如果想在线 DDL，需要确保以下两点： + 1. 多个集群的 CDC 构成一个单向 DDL 同步链，不能成环，例如示例中只有 C 集群的 CDC 关闭了 sync-ddl。 + 2. DDL 必须在单向 DDL 同步链的开始集群上执行，例如示例中的 A 集群。 diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md index f865021c110b..82131a341e4c 100644 --- a/tidb-lightning/tidb-lightning-configuration.md +++ b/tidb-lightning/tidb-lightning-configuration.md @@ -125,6 +125,9 @@ no-schema = false # 注意：**数据** 文件始终解析为 binary 文件。 character-set = "auto" +# 只导入与该通配符规则相匹配的表。详情见相应章节。 +filter = ['*.*'] + # 配置 CSV 文件的解析方式。 [mydumper.csv] # 字段分隔符，应为单个 ASCII 字符。 @@ -195,10 +198,6 @@ analyze = true switch-mode = "5m" # 在日志中打印导入进度的持续时间。 log-progress = "5m" - -# 设置表库过滤。详情参见“TiDB Lightning 表库过滤”文档。 -# [black-white-list] -# ... ``` ### TiKV Importer 配置参数 @@ -281,7 +280,12 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | +<<<<<<< HEAD | --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | +======= +| -f *rule* | [表库过滤的规则](/table-filter.md) (可多次指定) | `mydumper.filter` | +| --backend *backend* | 选择后端的模式：`importer` `local` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | +>>>>>>> a4c0315... *: replace black-white-list by table filter (#3916) | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | | --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | diff --git a/tidb-lightning/tidb-lightning-glossary.md b/tidb-lightning/tidb-lightning-glossary.md index 80ddb2de7290..7cf687dfbd93 100644 --- a/tidb-lightning/tidb-lightning-glossary.md +++ b/tidb-lightning/tidb-lightning-glossary.md @@ -35,12 +35,6 @@ aliases: ['/docs-cn/v3.0/reference/tools/tidb-lightning/glossary/'] 详情参阅 [TiDB Lightning TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md)。 -### Black-white list - -黑白名单配置列表。用于指定要导入、忽略哪些表和库。 - -详情参阅 [TiDB Lightning 表库过滤](/tidb-lightning/tidb-lightning-table-filter.md)。 - ## C @@ -105,6 +99,16 @@ TiDB Lightning 通过引擎将数据传送到 TiKV Importer 中。Lightning 先 另见[数据引擎](#data-engine)和[索引引擎](#index-engine)。 + + +## F + +### Filter + +配置列表，用于指定需要导入或不允许导入的表。 + +详情见[表库过滤](/table-filter.md)。 + ## I From dfc806e564c6b80e06f54a989ef428bf158e3f0b Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 13 Jul 2020 11:57:04 +0800 Subject: [PATCH 2/4] resolve conflict and apply version specific changes --- TOC.md | 224 +------ br/backup-and-restore-tool.md | 575 ------------------ table-filter.md | 26 +- ticdc/manage-ticdc.md | 555 ----------------- .../tidb-lightning-configuration.md | 6 +- 5 files changed, 5 insertions(+), 1381 deletions(-) delete mode 100644 br/backup-and-restore-tool.md delete mode 100644 ticdc/manage-ticdc.md diff --git a/TOC.md b/TOC.md index 7c47763aec00..8324fde5aa66 100644 --- a/TOC.md +++ b/TOC.md @@ -6,7 +6,6 @@ ## 目录 + 关于 TiDB -<<<<<<< HEAD - [TiDB 简介](/overview.md) + Benchmark 测试 - [如何用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md) @@ -74,226 +73,6 @@ - [集群配置诊断](/troubleshoot-tidb-cluster.md) - [TiDB Lightning 故障诊断](/troubleshoot-tidb-lightning.md) + 参考手册 -======= - + [TiDB 简介](/overview.md) - + [What's New in TiDB 4.0](/whats-new-in-tidb-4.0.md) - + [基本功能](/basic-features.md) - + 兼容性 - + [与 MySQL 的兼容性](/mysql-compatibility.md) - + [使用限制](/tidb-limitations.md) - + [荣誉列表](/credits.md) -+ 快速上手 - + [快速上手指南](/quick-start-with-tidb.md) - + [SQL 基本操作](/basic-sql-operations.md) -+ 部署集群 - + [软硬件环境需求](/hardware-and-software-requirements.md) - + [环境与系统配置检查](/check-before-deployment.md) - + 配置拓扑结构 - + [最小部署拓扑结构](/minimal-deployment-topology.md) - + [TiFlash 部署拓扑](/tiflash-deployment-topology.md) - + [TiCDC 部署拓扑](/ticdc-deployment-topology.md) - + [TiDB Binlog 部署拓扑](/tidb-binlog-deployment-topology.md) - + [跨机房部署拓扑结构](/geo-distributed-deployment-topology.md) - + [混合部署拓扑结构](/hybrid-deployment-topology.md) - + 安装与启动 - + Linux 环境 - + [使用 TiUP 部署（推荐）](/production-deployment-using-tiup.md) - + [使用 TiUP 离线部署（推荐）](/production-offline-deployment-using-tiup.md) - + [使用 Ansible 部署](/online-deployment-using-ansible.md) - + [使用 Ansible 离线部署](/offline-deployment-using-ansible.md) - + [验证集群状态](/post-installation-check.md) - + 性能测试报告及重现指南 - + [如何用 Sysbench 测试 TiDB](/benchmark/benchmark-tidb-using-sysbench.md) - + [如何对 TiDB 进行 TPC-C 测试](/benchmark/benchmark-tidb-using-tpcc.md) - + [Sysbench 性能对比 - v4.0 对比 v3.0](/benchmark/benchmark-sysbench-v4-vs-v3.md) - + [TPC-H 性能对比 - v4.0 对比 v3.0](/benchmark/v4.0-performance-benchmarking-with-tpch.md) - + [TPC-C 性能对比 - v4.0 对比 v3.0](/benchmark/v4.0-performance-benchmarking-with-tpcc.md) - + [Sysbench 性能对比 - v3.0 对比 v2.1](/benchmark/v3.0-performance-benchmarking-with-sysbench.md) - + [TPC-C 性能对比 - v3.0 对比 v2.1](/benchmark/v3.0-performance-benchmarking-with-tpcc.md) - + [线上负载与 ADD INDEX 相互影响测试](/benchmark/online-workloads-and-add-index-operations.md) -+ 数据迁移 - + [概述](/migration-overview.md) - + 从 MySQL 迁移至 TiDB - + [从 Mydumper 文件迁移](/migrate-from-mysql-mydumper-files.md) - + [使用 DM 工具从 Amazon Aurora MySQL 迁移](/migrate-from-aurora-mysql-database.md) - + 从 CSV 文件迁移至 TiDB - + [使用 TiDB Lightning 导入 CSV 文件](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) - + [使用 LOAD DATA 语句导入 CSV 文件](/sql-statements/sql-statement-load-data.md) - + [从 SQL 文件迁移到 TiDB](/migrate-from-mysql-mydumper-files.md) -+ 运维操作 - + 升级 TiDB 版本 - + [使用 TiUP 升级（推荐）](/upgrade-tidb-using-tiup.md) - + [使用 TiUP 离线升级（推荐）](/upgrade-tidb-using-tiup-offline.md) - + [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/upgrade-a-tidb-cluster) - + [使用 TiDB Ansible](/upgrade-tidb-using-ansible.md) - + 扩缩容 - + [使用 TiUP（推荐）](/scale-tidb-using-tiup.md) - + [使用 TiDB Ansible](/scale-tidb-using-ansible.md) - + [使用 TiDB Operator](https://docs.pingcap.com/zh/tidb-in-kubernetes/v1.1/scale-a-tidb-cluster) - + 备份与恢复 - + 使用 BR 工具（推荐） - + [使用 BR 进行备份与恢复](/br/backup-and-restore-tool.md) - + [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md) - + [使用 Dumpling 和 TiDB Lightning 进行备份与恢复（推荐）](/backup-and-restore-using-dumpling-lightning.md) - + [使用 Mydumper 和 TiDB Lightning 进行备份与恢复](/backup-and-restore-using-mydumper-lightning.md) - + [读取历史数据](/read-historical-data.md) - + [修改时区](/configure-time-zone.md) - + [日常巡检](/daily-check.md) - + [TiCDC 运维操作及任务管理](/ticdc/manage-ticdc.md) - + [TiFlash 常用运维操作](/tiflash/maintain-tiflash.md) - + [TiUP 常用运维操作](/maintain-tidb-using-tiup.md) - + [Ansible 常用运维操作](/maintain-tidb-using-ansible.md) -+ 监控与告警 - + [监控框架概述](/tidb-monitoring-framework.md) - + [监控 API](/tidb-monitoring-api.md) - + [手动部署监控](/deploy-monitoring-services.md) - + [TiDB 集群报警规则与处理方法](/alert-rules.md) - + [TiFlash 报警规则与处理方法](/tiflash/tiflash-alert-rules.md) -+ 故障诊断 - + [定位慢查询](/identify-slow-queries.md) - + [SQL 诊断](/system-tables/system-table-sql-diagnostics.md) - + [定位消耗系统资源多的查询](/identify-expensive-queries.md) - + [SQL 语句统计](/statement-summary-tables.md) - + [TiDB 集群常见问题](/troubleshoot-tidb-cluster.md) - + [TiDB 集群问题导图](/tidb-troubleshooting-map.md) - + [热点问题处理](/troubleshoot-hot-spot-issues.md) - + [CPU 占用过多导致读写延迟增加](/troubleshoot-cpu-issues.md) - + [写冲突与写性能下降](/troubleshoot-write-conflicts.md) - + [磁盘 I/O 过高](/troubleshoot-high-disk-io.md) - + [锁冲突与 TTL 超时](/troubleshoot-lock-conflicts.md) - + [TiCDC 常见问题](/ticdc/troubleshoot-ticdc.md) - + [TiFlash 常见问题](/tiflash/troubleshoot-tiflash.md) -+ 性能调优 - + 系统调优 - + [操作系统性能参数调优](/tune-operating-system.md) - + 软件调优 - + 配置 - + [TiDB 内存调优](/configure-memory-usage.md) - + [TiKV 线程调优](/tune-tikv-thread-performance.md) - + [TiKV 内存调优](/tune-tikv-memory-performance.md) - + [TiKV Follower Read](/follower-read.md) - + [TiFlash 调优](/tiflash/tune-tiflash-performance.md) - + [下推计算结果缓存](/coprocessor-cache.md) - + SQL 性能调优 - + [SQL 性能调优概览](/sql-tuning-overview.md) - + [理解 TiDB 执行计划](/query-execution-plan.md) - + SQL 优化 - + [SQL 优化流程简介](/sql-optimization-concepts.md) - + 逻辑优化 - + [逻辑优化概览](/sql-logical-optimization.md) - + [子查询相关的优化](/subquery-optimization.md) - + [列裁剪](/column-pruning.md) - + [关联子查询去关联](/correlated-subquery-optimization.md) - + [Max/Min 消除](/max-min-eliminate.md) - + [谓词下推](/predicate-push-down.md) - + [分区裁剪](/partition-pruning.md) - + [TopN 和 Limit 下推](/topn-limit-push-down.md) - + [Join Reorder](/join-reorder.md) - + 物理优化 - + [物理优化概览](/sql-physical-optimization.md) - + [索引的选择](/choose-index.md) - + [统计信息简介](/statistics.md) - + [错误索引的解决方案](/wrong-index-solution.md) - + [Distinct 优化](/agg-distinct-optimization.md) - + [执行计划缓存](/sql-prepare-plan-cache.md) - + 控制执行计划 - + [控制执行计划概览](/control-execution-plan.md) - + [Optimizer Hints](/optimizer-hints.md) - + [执行计划管理](/sql-plan-management.md) - + [优化规则及表达式下推的黑名单](/blacklist-control-plan.md) -+ 教程 - + [同城多中心部署](/multi-data-centers-in-one-city-deployment.md) - + [两地三中心部署](/three-data-centers-in-two-cities-deployment.md) - + 最佳实践 - + [TiDB 最佳实践](/best-practices/tidb-best-practices.md) - + [Java 应用开发最佳实践](/best-practices/java-app-best-practices.md) - + [HAProxy 最佳实践](/best-practices/haproxy-best-practices.md) - + [高并发写入场景最佳实践](/best-practices/high-concurrency-best-practices.md) - + [Grafana 监控最佳实践](/best-practices/grafana-monitor-best-practices.md) - + [PD 调度策略最佳实践](/best-practices/pd-scheduling-best-practices.md) - + [海量 Region 集群调优](/best-practices/massive-regions-best-practices.md) - + [Placement Rules 使用文档](/configure-placement-rules.md) - + [Load Base Split 使用文档](/configure-load-base-split.md) - + [Store Limit 使用文档](/configure-store-limit.md) -+ TiDB 生态工具 - + [功能概览](/ecosystem-tool-user-guide.md) - + [适用场景](/ecosystem-tool-user-case.md) - + [工具下载](/download-ecosystem-tools.md) - + Backup & Restore (BR) - + [BR 常见问题](/br/backup-and-restore-faq.md) - + [使用 BR 进行备份和恢复](/br/backup-and-restore-tool.md) - + [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md) - + TiDB Binlog - + [概述](/tidb-binlog/tidb-binlog-overview.md) - + [快速上手](/tidb-binlog/get-started-with-tidb-binlog.md) - + [部署使用](/tidb-binlog/deploy-tidb-binlog.md) - + [运维管理](/tidb-binlog/maintain-tidb-binlog-cluster.md) - + [配置说明](/tidb-binlog/tidb-binlog-configuration-file.md) - + [Pump](/tidb-binlog/tidb-binlog-configuration-file.md#pump) - + [Drainer](/tidb-binlog/tidb-binlog-configuration-file.md#drainer) - + [版本升级](/tidb-binlog/upgrade-tidb-binlog.md) - + [监控告警](/tidb-binlog/monitor-tidb-binlog-cluster.md) - + [增量恢复](/tidb-binlog/tidb-binlog-reparo.md) - + [binlogctl 工具](/tidb-binlog/binlog-control.md) - + [Kafka 自定义开发](/tidb-binlog/binlog-slave-client.md) - + [TiDB Binlog Relay Log](/tidb-binlog/tidb-binlog-relay-log.md) - + [集群间双向同步](/tidb-binlog/bidirectional-replication-between-tidb-clusters.md) - + [术语表](/tidb-binlog/tidb-binlog-glossary.md) - + 故障诊断 - + [故障诊断](/tidb-binlog/troubleshoot-tidb-binlog.md) - + [常见错误修复](/tidb-binlog/handle-tidb-binlog-errors.md) - + [FAQ](/tidb-binlog/tidb-binlog-faq.md) - + TiDB Lightning - + [概述](/tidb-lightning/tidb-lightning-overview.md) - + [快速上手教程](/get-started-with-tidb-lightning.md) - + [部署执行](/tidb-lightning/deploy-tidb-lightning.md) - + [参数说明](/tidb-lightning/tidb-lightning-configuration.md) - + 主要功能 - + [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md) - + [表库过滤](/table-filter.md) - + [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) - + [TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md) - + [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md) - + [监控告警](/tidb-lightning/monitor-tidb-lightning.md) - + [故障诊断](/troubleshoot-tidb-lightning.md) - + [FAQ](/tidb-lightning/tidb-lightning-faq.md) - + [术语表](/tidb-lightning/tidb-lightning-glossary.md) - + [TiCDC](/ticdc/ticdc-overview.md) - + [Dumpling](/dumpling-overview.md) - + sync-diff-inspector - + [概述](/sync-diff-inspector/sync-diff-inspector-overview.md) - + [不同库名或表名的数据校验](/sync-diff-inspector/route-diff.md) - + [分库分表场景下的数据校验](/sync-diff-inspector/shard-diff.md) - + [TiDB 主从集群的数据校验](/sync-diff-inspector/upstream-downstream-diff.md) - + [Loader](/loader-overview.md) - + [Mydumper](/mydumper-overview.md) - + [Syncer](/syncer-overview.md) - + TiSpark - + [TiSpark 快速上手](/get-started-with-tispark.md) - + [TiSpark 用户指南](/tispark-overview.md) -+ 参考指南 - + 架构 - + [概述](/tidb-architecture.md) - + [存储](/tidb-storage.md) - + [计算](/tidb-computing.md) - + [调度](/tidb-scheduling.md) - + 监控指标 - + [Overview 面板](/grafana-overview-dashboard.md) - + [TiDB 面板](/grafana-tidb-dashboard.md) - + [PD 面板](/grafana-pd-dashboard.md) - + [TiKV 面板](/grafana-tikv-dashboard.md) - + [TiFlash 监控指标](/tiflash/monitor-tiflash.md) - + 安全加固 - + [为 TiDB 客户端服务端间通信开启加密传输](/enable-tls-between-clients-and-servers.md) - + [为 TiDB 组件间通信开启加密传输](/enable-tls-between-components.md) - + [生成自签名证书](/generate-self-signed-certificates.md) - + 权限 - + [与 MySQL 安全特性差异](/security-compatibility-with-mysql.md) - + [权限管理](/privilege-management.md) - + [TiDB 用户账户管理](/user-account-management.md) - + [基于角色的访问控制](/role-based-access-control.md) - + [TiDB 证书鉴权使用指南](/certificate-authentication.md) ->>>>>>> a4c0315... *: replace black-white-list by table filter (#3916) + SQL - [与 MySQL 兼容性对比](/mysql-compatibility.md) + SQL 语言结构 @@ -524,6 +303,7 @@ + 周边工具 - [功能概览](/ecosystem-tool-user-guide.md) - [适用场景](/ecosystem-tool-user-case.md) + - [表库过滤](/table-filter.md) - [Mydumper](/mydumper-overview.md) - [Loader](/loader-overview.md) - [Syncer](/syncer-overview.md) @@ -533,7 +313,7 @@ - [部署执行](/tidb-lightning/deploy-tidb-lightning.md) - [参数说明](/tidb-lightning/tidb-lightning-configuration.md) - [断点续传](/tidb-lightning/tidb-lightning-checkpoints.md) - - [表库过滤](/tidb-lightning/tidb-lightning-table-filter.md) + - [表库过滤](/table-filter.md) - [CSV 支持](/tidb-lightning/migrate-from-csv-using-tidb-lightning.md) - [TiDB-backend](/tidb-lightning/tidb-lightning-tidb-backend.md) - [Web 界面](/tidb-lightning/tidb-lightning-web-interface.md) diff --git a/br/backup-and-restore-tool.md b/br/backup-and-restore-tool.md deleted file mode 100644 index 94148ed7af35..000000000000 --- a/br/backup-and-restore-tool.md +++ /dev/null @@ -1,575 +0,0 @@ ---- -title: 使用 BR 进行备份与恢复 -summary: 了解如何使用 BR 工具进行集群数据备份和恢复。 -category: how-to -aliases: ['/docs-cn/dev/reference/tools/br/br/','/docs-cn/dev/how-to/maintain/backup-and-restore/br/'] ---- - -# 使用 BR 进行备份与恢复 - -Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 [`mydumper`/`loader`](/backup-and-restore-using-mydumper-lightning.md)，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。 - -## 使用限制 - -- BR 只支持 TiDB v3.1 及以上版本。 -- 目前只支持在全新的集群上执行恢复操作。 -- BR 备份最好串行执行，否则不同备份任务之间会相互影响。 -- BR 只支持在 `new_collations_enabled_on_first_bootstrap` [开关值](/character-set-and-collation.md#排序规则支持)相同的集群之间进行操作。这是因为 BR 仅备份 KV 数据。如果备份集群和恢复集群采用不同的排序规则，数据校验会不通过。所以恢复集群时，你需要确保 `select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME='new_collation_enabled';` 语句的开关值查询结果与备份时的查询结果相一致，才可以进行恢复。 - - - 对于 v3.1 集群，TiDB 尚未支持 new collation，因此可以认为 new collation 未打开 - - 对于 v4.0 集群，请通过 `SELECT VARIABLE_VALUE FROM mysql.tidb WHERE VARIABLE_NAME='new_collation_enabled';` 查看 new collation 是否打开。 - - 例如，数据备份在 v3.1 集群。如果恢复到 v4.0 集群中，查询恢复集群的 `new_collation_enabled` 的值为 `true`，则说明创建恢复集群时打开了 new collation 支持的开关。此时恢复数据，可能会出错。 - -## 推荐部署配置 - -- 推荐 BR 部署在 PD 节点上。 -- 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。 - -## 下载 Binary - -详见[下载链接](/download-ecosystem-tools.md#快速备份和恢复br)。 - -## 工作原理 - -BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。更多信息请参阅[备份恢复设计方案](https://github.com/pingcap/br/blob/980627aa90e5d6f0349b423127e0221b4fa09ba0/docs/cn/2019-08-05-new-design-of-backup-restore.md) - -![br-arch](/media/br-arch.png) - -### 备份文件类型 - -备份路径下会生成以下两种类型文件： - -- SST 文件：存储 TiKV 备份下来的数据信息 -- `backupmeta` 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值 - -### SST 文件命名格式 - -SST 文件以 `storeID_regionID_regionEpoch_keyHash_cf` 的格式命名。格式名的解释如下： - -- storeID：TiKV 节点编号 -- regionID：Region 编号 -- regionEpoch：Region 版本号 -- keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性 -- cf：RocksDB 的 ColumnFamily（默认为 `default` 或 `write`） - -## BR 命令行描述 - -一条 `br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。 - -以下是一条完整的 `br` 命令行： - -`br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"` - -命令行各部分的解释如下： - -* `backup`：`br` 的子命令 -* `full`：`backup` 的子命令 -* `-s` 或 `--storage`：备份保存的路径 -* `"local:///tmp/backup"`：`-s` 的参数，保存的路径为各个 TiKV 节点本地磁盘的 `/tmp/backup` -* `--pd`：PD 服务地址 -* `"${PDIP}:2379"`：`--pd` 的参数 - -> **注意：** -> -> 在使用 `local` storage 的时候，备份数据会分散在各个节点的本地文件系统中。 -> -> **不建议**在生产环境中备份到本地磁盘，因为在日后恢复的时候，**必须**手动聚集这些数据才能完成恢复工作（见[恢复集群数据](#恢复集群数据)）。 -> -> 聚集这些备份数据可能会造成数据冗余和运维上的麻烦，而且在不聚集这些数据便直接恢复的时候会遇到颇为迷惑的 `SST file not found` 报错。 -> -> 建议在各个节点挂载 NFS 网盘，或者直接备份到 `S3` 对象存储中。 - -### 命令和子命令 - -BR 由多层命令组成。目前，BR 包含 `backup`、`restore` 和 `version` 三个子命令: - -* `br backup` 用于备份 TiDB 集群 -* `br restore` 用于恢复 TiDB 集群 -* `br version` 用于查看 BR 工具版本信息 - -以上三个子命令可能还包含这些子命令： - -* `full`：可用于备份或恢复全部数据。 -* `db`：可用于备份或恢复集群中的指定数据库。 -* `table`：可用于备份或恢复集群指定数据库中的单张表。 - -### 常用选项 - -* `--pd`：用于连接的选项，表示 PD 服务地址，例如 `"${PDIP}:2379"`。 -* `-h`/`--help`：获取所有命令和子命令的使用帮助。例如 `br backup --help`。 -* `--ca`：指定 PEM 格式的受信任 CA 的证书文件路径。 -* `--cert`：指定 PEM 格式的 SSL 证书文件路径。 -* `--key`：指定 PEM 格式的 SSL 证书密钥文件路径。 -* `--status-addr`：BR 向 Prometheus 提供统计数据的监听地址。 - -## 备份集群数据 - -使用 `br backup` 命令来备份集群数据。可选择添加 `full` 或 `table` 子命令来指定备份的范围：全部集群数据或单张表的数据。 - -如果备份时间可能超过设定的 [`tikv_gc_life_time`](/garbage-collection-configuration.md#tikv_gc_life_time)（默认 `10m0s`，即表示 10 分钟），则需要将该参数调大。 - -例如，将 `tikv_gc_life_time` 调整为 `720h`： - -{{< copyable "sql" >}} - -```sql -mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \ - "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'"; -``` - -### 备份全部集群数据 - -要备份全部集群数据，可使用 `br backup full` 命令。该命令的使用帮助可以通过 `br backup full -h` 或 `br backup full --help` 来获取。 - -用例：将所有集群数据备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -> **注意：** -> -> + 经测试，在全速备份的情况下，如果备份盘和服务盘不同，在线备份会让只读线上服务的 QPS 下降 15%~25% 左右。如果希望降低影响，请参考 `--ratelimit` 进行限速。 -> + 假如备份盘和服务盘相同，备份将会和服务争夺 I/O 资源，这可能会让只读线上服务的 QPS 骤降一半以上。请尽量禁止将在线服务的数据备份到 TiKV 的数据盘。 - -{{< copyable "shell-regular" >}} - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --log-file backupfull.log -``` - -以上命令中，`--ratelimit` 选项限制了**每个 TiKV** 执行备份任务的速度上限（单位 MiB/s）。`--log-file` 选项指定把 BR 的 log 写到 `backupfull.log` 文件中。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下： - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --log-file backupfull.log -Full Backup <---------/................................................> 17.12%. -``` - -### 备份单个数据库的数据 - -要备份集群中指定单个数据库的数据，可使用 `br backup db` 命令。同样可通过 `br backup db -h` 或 `br backup db --help` 来获取子命令 `db` 的使用帮助。 - -用例：将数据库 `test` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup db \ - --pd "${PDIP}:2379" \ - --db test \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --log-file backuptable.log -``` - -`db` 子命令的选项为 `--db`，用来指定数据库名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -### 备份单张表的数据 - -要备份集群中指定单张表的数据，可使用 `br backup table` 命令。同样可通过 `br backup table -h` 或 `br backup table --help` 来获取子命令 `table` 的使用帮助。 - -用例：将表 `test.usertable` 备份到各个 TiKV 节点的 `/tmp/backup` 路径，同时也会将备份的元信息文件 `backupmeta` 写到该路径下。 - -{{< copyable "shell-regular" >}} - -```shell -br backup table \ - --pd "${PDIP}:2379" \ - --db test \ - --table usertable \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --log-file backuptable.log -``` - -`table` 子命令有 `--db` 和 `--table` 两个选项，分别用来指定数据库名和表名。其他选项的含义与[备份全部集群数据](#备份全部集群数据)相同。 - -备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。 - -### 使用表库过滤功能备份多张表的数据 - -如果你需要以更复杂的过滤条件来备份多个表，执行 `br backup full` 命令，并使用 `--filter` 或 `-f` 来指定[表库过滤](/table-filter.md)规则。 - -用例：以下命令将所有 `db*.tbl*` 形式的表格数据备份到每个 TiKV 节点上的 `/tmp/backup` 路径，并将 `backupmeta` 文件写入该路径。 - -{{< copyable "shell-regular" >}} - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --filter 'db*.tbl*' \ - --storage "local:///tmp/backup" \ - --ratelimit 120 \ - --log-file backupfull.log -``` - -### 备份数据到 Amazon S3 后端存储 - -如果备份的存储并不是在本地，而是在 Amazon 的 S3 后端存储，那么需要在 `storage` 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。 - -这里可以参照 [AWS 官方文档](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/user-guide/create-bucket.html)在指定的 `Region` 区域中创建一个 S3 桶 `Bucket`，如果有需要，还可以参照 [AWS 官方文档](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/user-guide/create-folder.html) 在 Bucket 中创建一个文件夹 `Folder`。 - -将有权限访问该 S3 后端存储的账号的 `SecretKey` 和 `AccessKey` 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。 - -{{< copyable "shell-regular" >}} - -```shell -export AWS_ACCESS_KEY_ID=${AccessKey} -export AWS_SECRET_ACCESS_KEY=${SecretKey} -``` - -在进行 BR 备份时，显示指定参数 `--s3.region` 和 `--send-credentials-to-tikv`, `--s3.region` 表示 S3 存储所在的区域，`--send-credentials-to-tikv` 表示将 S3 的访问权限传递给 TiKV 节点。 - -{{< copyable "shell-regular" >}} - -```shell -br backup full \ - --pd "${PDIP}:2379" \ - --storage "s3://${Bucket}/${Folder}" \ - --s3.region "${region}" \ - --send-credentials-to-tikv true \ - --log-file backuptable.log -``` - -### 增量备份 - -如果想要备份增量，只需要在备份的时候指定**上一次的备份时间戳** `--lastbackupts` 即可。 - -注意增量备份有以下限制： - -- 增量备份需要与前一次全量备份在不同的路径下 -- GC safepoint 必须在 `lastbackupts` 之前 - -{{< copyable "shell-regular" >}} - -```shell -br backup full\ - --pd ${PDIP}:2379 \ - -s local:///home/tidb/backupdata/incr \ - --lastbackupts ${LAST_BACKUP_TS} -``` - -以上命令会备份 `(LAST_BACKUP_TS, current PD timestamp]` 之间的增量数据。 - -你可以使用 `validate` 指令获取上一次备份的时间戳，示例如下： - -{{< copyable "shell-regular" >}} - -```shell -LAST_BACKUP_TS=`br validate decode --field="end-version" -s local:///home/tidb/backupdata` -``` - -示例备份的增量数据包括 `(LAST_BACKUP_TS, current PD timestamp]` 之间的新写入数据，以及这段时间内的 DDL。在恢复的时候，BR 会先把所有 DDL 恢复，而后才会恢复写入数据。 - -### Raw KV 备份（实验性功能） - -> **警告：** -> -> Raw KV 备份功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。 - -在某些使用场景下，TiKV 可能会独立于 TiDB 运行。考虑到这点，BR 也提供跳过 TiDB 层，直接备份 TiKV 中数据的功能： - -{{< copyable "shell-regular" >}} - -```shell -br backup raw --pd $PD_ADDR \ - -s "local://$BACKUP_DIR" \ - --start 31 \ - --end 3130303030303030 \ - --format hex \ - --cf default -``` - -以上命令会备份 default CF 上 `[0x31, 0x3130303030303030)` 之间的所有键到 `$BACKUP_DIR` 去。 - -这里，`--start` 和 `--end` 的参数会先依照 `--format` 指定的方式解码，再被送到 TiKV 上去，目前支持以下解码方式： - -- "raw"：不进行任何操作，将输入的字符串直接编码为二进制格式的键。 -- "hex"：将输入的字符串视作十六进制数字。这是默认的编码方式。 -- "escape"：对输入的字符串进行转义之后，再编码为二进制格式。 - -## 恢复集群数据 - -使用 `br restore` 命令来恢复备份数据。可选择添加 `full`、`db` 或 `table` 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。 - -> **注意：** -> -> 如果使用本地存储，在恢复前**必须**将所有备份的 SST 文件复制到各个 TiKV 节点上 `--storage` 指定的目录下。 -> -> 即使每个 TiKV 节点最后只需要读取部分 SST 文件，这些节点也需要有所有 SST 文件的完全访问权限。原因如下： -> -> * 数据被复制到了多个 Peer 中。在读取 SST 文件时，这些文件必须要存在于所有 Peer 中。这与数据的备份不同，在备份时，只需从单个节点读取。 -> * 在数据恢复的时候，每个 Peer 分布的位置是随机的，事先并不知道哪个节点将读取哪个文件。 -> -> 使用共享存储可以避免这些情况。例如，在本地路径上安装 NFS，或使用 S3。利用这些网络存储，各个节点都可以自动读取每个 SST 文件，此时上述注意事项不再适用。 - -### 恢复全部备份数据 - -要将全部备份数据恢复到集群中来，可使用 `br restore full` 命令。该命令的使用帮助可以通过 `br restore full -h` 或 `br restore full --help` 来获取。 - -用例：将 `/tmp/backup` 路径中的全部备份数据恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --ratelimit 128 \ - --log-file restorefull.log -``` - -以上命令中，`--ratelimit` 选项限制了**每个 TiKV** 执行恢复任务的速度上限（单位 MiB/s）。`--log-file` 选项指定把 BR 的 log 写到 `restorefull.log` 文件中。 - -恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下： - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -Full Restore <---------/...............................................> 17.12%. -``` - -### 恢复单个数据库的数据 - -要将备份数据中的某个数据库恢复到集群中，可以使用 `br restore db` 命令。该命令的使用帮助可以通过 `br restore db -h` 或 `br restore db --help` 来获取。 - -用例：将 `/tmp/backup` 路径中备份数据中的某个数据库恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore db \ - --pd "${PDIP}:2379" \ - --db "test" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -以上命令中 `--db` 选项指定了需要恢复的数据库名字。其余选项的含义与[恢复全部备份数据](#恢复全部备份数据)相同。 - -### 恢复单张表的数据 - -要将备份数据中的某张数据表恢复到集群中，可以使用 `br restore table` 命令。该命令的使用帮助可通过 `br restore table -h` 或 `br restore table --help` 来获取。 - -用例：将 `/tmp/backup` 路径下的备份数据中的某个数据表恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore table \ - --pd "${PDIP}:2379" \ - --db "test" \ - --table "usertable" \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -### 使用表库功能过滤恢复数据 - -如果你需要用复杂的过滤条件来恢复多个表，执行 `br restore full` 命令，并用 `--filter` 或 `-f` 指定使用[表库过滤](/table-filter.md)。 - -用例：以下命令将备份在 `/tmp/backup` 路径的表的子集恢复到集群中。 - -{{< copyable "shell-regular" >}} - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --filter 'db*.tbl*' \ - --storage "local:///tmp/backup" \ - --log-file restorefull.log -``` - -### 从 Amazon S3 后端存储恢复数据 - -如果需要恢复的数据并不是存储在本地，而是在 Amazon 的 S3 后端，那么需要在 `storage` 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。 - -将有权限访问该 S3 后端存储的账号的 `SecretKey` 和 `AccessKey` 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。 - -{{< copyable "shell-regular" >}} - -```shell -export AWS_ACCESS_KEY_ID=${AccessKey} -export AWS_SECRET_ACCESS_KEY=${SecretKey} -``` - -在进行 BR 恢复时，显示指定参数 `--s3.region` 和 `--send-credentials-to-tikv`, `--s3.region` 表示 S3 存储所在的区域，`--send-credentials-to-tikv` 表示将 S3 的访问权限传递给 TiKV 节点。`--storage`参数中的 `Bucket` 和 `Folder` 分别代表需要恢复的数据所在的 S3 存储桶和文件夹。 - -{{< copyable "shell-regular" >}} - -```shell -br restore full \ - --pd "${PDIP}:2379" \ - --storage "s3://${Bucket}/${Folder}" \ - --s3.region "${region}" \ - --send-credentials-to-tikv=true \ - --log-file restorefull.log -``` - -以上命令中 `--table` 选项指定了需要恢复的表名。其余选项的含义与[恢复单个数据库](#恢复单个数据库的数据)相同。 - -### 增量恢复 - -增量恢复的方法和使用 BR 进行全量恢复的方法并无差别。需要注意，恢复增量数据的时候，需要保证备份时指定的 `last backup ts` 之前备份的数据已经全部恢复到目标集群。 - -### Raw KV 恢复（实验性功能） - -> **警告：** -> -> Raw KV 恢复功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。 - -和 [Raw KV 备份](#raw-kv-备份实验性功能)相似地，恢复 Raw KV 的命令如下： - -{{< copyable "shell-regular" >}} - -```shell -br restore raw --pd $PD_ADDR \ - -s "local://$BACKUP_DIR" \ - --start 31 \ - --end 3130303030303030 \ - --format hex \ - --cf default -``` - -以上命令会将范围在 `[0x31, 0x3130303030303030)` 的已备份键恢复到 TiKV 集群中。这里键的编码方式和备份时相同。 - -### 在线恢复（实验性功能） - -> **警告：** -> -> 在线恢复功能还在实验中，没有经过完备的测试，同时还依赖 PD 的不稳定特性 Placement Rules。暂时请避免在生产环境中使用该功能。 - -在恢复的时候，写入过多的数据会影响在线集群的性能。为了尽量避免影响线上业务，BR 支持通过 [Placement rules](/configure-placement-rules.md) 隔离资源。让下载、导入 SST 的工作仅仅在指定的几个节点（下称“恢复节点”）上进行，具体操作如下： - -1. 配置 PD，启动 Placement rules： - - {{< copyable "shell-regular" >}} - - ```shell - echo "config set enable-placement-rules true" | pd-ctl - ``` - -2. 编辑恢复节点 TiKV 的配置文件，在 `server` 一项中指定： - - {{< copyable "" >}} - - ``` - [server] - labels = { exclusive = "restore" } - ``` - -3. 启动恢复节点的 TiKV，使用 BR 恢复备份的文件，和非在线恢复相比，这里只需要加上 `--online` 标志即可： - - {{< copyable "shell-regular" >}} - - ``` - br restore full \ - -s "local://$BACKUP_DIR" \ - --pd $PD_ADDR \ - --online - ``` - -## 最佳实践 - -- 推荐在 `-s` 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。 -- 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。 -- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。 - -更多最佳实践内容，参见 [BR 备份与恢复场景示例](/br/backup-and-restore-use-cases.md)。 - -## 备份和恢复示例 - -本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。 - -### 数据规模和机器配置 - -假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。 - -```sql -MySQL [sbtest]> show tables; -+------------------+ -| Tables_in_sbtest | -+------------------+ -| sbtest1 | -| sbtest10 | -| sbtest2 | -| sbtest3 | -| sbtest4 | -| sbtest5 | -| sbtest6 | -| sbtest7 | -| sbtest8 | -| sbtest9 | -+------------------+ - -MySQL [sbtest]> select count(*) from sbtest1; -+----------+ -| count(*) | -+----------+ -| 5000000 | -+----------+ -1 row in set (1.04 sec) -``` - -表结构如下： - -```sql -CREATE TABLE `sbtest1` ( - `id` int(11) NOT NULL AUTO_INCREMENT, - `k` int(11) NOT NULL DEFAULT '0', - `c` char(120) NOT NULL DEFAULT '', - `pad` char(60) NOT NULL DEFAULT '', - PRIMARY KEY (`id`), - KEY `k_1` (`k`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499 -``` - -示例假设有 4 个 TiKV 节点，每个节点配置如下： - -| CPU | 内存 | 磁盘 | 副本数 | -| :--- | :--- | :--- | :--- | -| 16 核 | 32 GB | SSD | 3 | - -### 备份示例 - -- 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断 -- 备份前需确认 TiDB 集群没有执行 DDL 操作 - -执行以下命令对集群中的全部数据进行备份： - -{{< copyable "shell-regular" >}} - -``` -bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log -``` - -``` -[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs] -``` - -### 恢复示例 - -恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。 - -执行以下命令对全部数据进行恢复： - -{{< copyable "shell-regular" >}} - -``` -bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log -``` - -``` -[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms] -``` diff --git a/table-filter.md b/table-filter.md index a80728bf652b..378bef6e753e 100644 --- a/table-filter.md +++ b/table-filter.md @@ -1,14 +1,14 @@ --- title: 表库过滤 summary: 在 TiDB 生态工具中使用表库过滤功能。 -aliases: ['/docs-cn/dev/tidb-lightning/tidb-lightning-table-filter/','/docs-cn/dev/reference/tools/tidb-lightning/table-filter/','/zh/tidb/dev/tidb-lightning-table-filter/'] +aliases: ['/docs-cn/v3.0/tidb-lightning/tidb-lightning-table-filter/','/docs-cn/v3.0/reference/tools/tidb-lightning/table-filter/','/zh/tidb/v3.0/tidb-lightning-table-filter/'] --- # 表库过滤 TiDB 生态工具默认情况下作用于所有数据库，但实际使用中，往往只需要作用于其中的部分子集。例如，用户只想处理 `foo*` 和 `bar*` 形式的表，而无需对其他表进行操作。 -从 TiDB 4.0 起，所有 TiDB 生态系统工具都使用一个通用的过滤语法来定义子集。本文档介绍如何使用表库过滤功能。 +所有 TiDB 生态系统工具都使用一个通用的过滤语法来定义子集。本文档介绍如何使用表库过滤功能。 ## 使用表库过滤 @@ -16,17 +16,6 @@ TiDB 生态工具默认情况下作用于所有数据库，但实际使用中， 在命令行中使用多个 `-f` 或 `--filter` 参数，即可在 TiDB 生态工具中应用表库过滤规则。每个过滤规则均采用 `db.table` 形式，支持通配符（详情见[下一节](#使用通配符)）。以下为各个工具中的使用示例： -* [BR](/br/backup-and-restore-tool.md)： - - {{< copyable "shell-regular" >}} - - ```shell - ./br backup full -f 'foo*.*' -f 'bar*.*' -s 'local:///tmp/backup' - # ^~~~~~~~~~~~~~~~~~~~~~~ - ./br restore full -f 'foo*.*' -f 'bar*.*' -s 'local:///tmp/backup' - # ^~~~~~~~~~~~~~~~~~~~~~~ - ``` - * [Dumpling](/backup-and-restore-using-dumpling-lightning.md)： {{< copyable "shell-regular" >}} @@ -56,17 +45,6 @@ TiDB 生态工具默认情况下作用于所有数据库，但实际使用中， filter = ['foo*.*', 'bar*.*'] ``` -* [TiCDC](/ticdc/ticdc-overview.md)： - - ```toml - [filter] - rules = ['foo*.*', 'bar*.*'] - - [[sink.dispatchers]] - matcher = ['db1.*', 'db2.*', 'db3.*'] - dispatcher = 'ts' - ``` - ## 表库过滤语法 ### 直接使用表名 diff --git a/ticdc/manage-ticdc.md b/ticdc/manage-ticdc.md deleted file mode 100644 index 31e7d6fd521f..000000000000 --- a/ticdc/manage-ticdc.md +++ /dev/null @@ -1,555 +0,0 @@ ---- -title: TiCDC 运维操作及任务管理 -category: reference -aliases: ['/docs-cn/dev/reference/tools/ticdc/manage/','/docs-cn/dev/reference/tools/ticdc/sink/','/docs-cn/dev/ticdc/sink-url/'] ---- - -# TiCDC 运维操作及任务管理 - -本文档介绍如何部署 TiCDC 集群，以及如何通过 TiCDC 提供的命令行工具 `cdc cli` 和 HTTP 接口两种方式来管理 TiCDC 集群和同步任务。 - -## TiCDC 部署 - -### 软件和硬件环境推荐配置 - -在生产环境中，TiCDC 的软件和硬件配置推荐如下： - -| Linux 操作系统平台 | 版本 | -| :----------------------- | :----------: | -| Red Hat Enterprise Linux | 7.3 及以上 | -| CentOS | 7.3 及以上 | - -| **CPU** | **内存** | **硬盘类型** | **网络** | **实例数量(最低要求)** | -| --- | --- | --- | --- | --- | -| 16 核+ | 64 GB+ | SSD | 万兆网卡（2 块最佳） | 2 | - -更多信息参见 [TiDB 软件和硬件环境建议配置](/hardware-and-software-requirements.md) - -### 使用 TiUP 部署 - -#### 使用 TiUP 部署包含 TiCDC 组件的 TiDB 集群 - -详细操作参考[使用 TiUP 部署 TiCDC](/production-deployment-using-tiup.md#第-3-步编辑初始化配置文件)。 - -#### 使用 TiUP 在原有 TiDB 集群上新增 TiCDC 组件 - -1. 首先确认当前 TiDB 的版本支持 TiCDC，否则需要先升级 TiDB 集群至 4.0.0 rc.1 或更新版本。 - -2. 参考 [扩容 TiDB/TiKV/PD/TiCDC 节点](/scale-tidb-using-tiup.md#扩容-ticdc-节点) 章节对 TiCDC 进行部署。 - -### 在原有 TiDB 集群上使用 binary 部署 TiCDC 组件 - -假设 PD 集群有一个可以提供服务的 PD 节点（client URL 为 `10.0.10.25:2379`）。若要部署三个 TiCDC 节点，可以按照以下命令启动集群。只需要指定相同的 PD 地址，新启动的节点就可以自动加入 TiCDC 集群。 - -{{< copyable "shell-regular" >}} - -```shell -cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_1.log --addr=0.0.0.0:8301 --advertise-addr=127.0.0.1:8301 -cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_2.log --addr=0.0.0.0:8302 --advertise-addr=127.0.0.1:8302 -cdc server --pd=http://10.0.10.25:2379 --log-file=ticdc_3.log --addr=0.0.0.0:8303 --advertise-addr=127.0.0.1:8303 -``` - -对于 `cdc server` 命令中可用选项解释如下： - -- `gc-ttl`: TiCDC 在 PD 设置的服务级别 GC safepoint 的 TTL (Time To Live) 时长，单位为秒，默认值为 `86400`，即 24 小时。 -- `pd`: PD client 的 URL。 -- `addr`: TiCDC 的监听地址，提供服务的 HTTP API 查询地址和 Prometheus 查询地址。 -- `advertise-addr`: TiCDC 对外访问地址。 -- `tz`: TiCDC 服务使用的时区。TiCDC 在内部转换 timestamp 等时间数据类型和向下游同步数据时使用该时区，默认为进程运行本地时区。 -- `log-file`: TiCDC 进程运行日志的地址，默认为 `cdc.log`。 -- `log-level`: TiCDC 进程运行时默认的日志级别，默认为 `info`。 - -## 使用 `cdc cli` 工具来管理集群状态和数据同步 - -以下内容介绍如何使用 `cdc cli` 工具来管理集群状态和数据同步。在以下接口描述中，假设 PD 的监听 IP 地址为 `10.0.10.25`，端口为 `2379`。 - -### 管理 TiCDC 服务进程 (`capture`) - -- 查询 `capture` 列表： - - {{< copyable "shell-regular" >}} - - ```shell - cdc cli capture list --pd=http://10.0.10.25:2379 - ``` - - ``` - [ - { - "id": "6d92386a-73fc-43f3-89de-4e337a42b766", - "is-owner": true - }, - { - "id": "b293999a-4168-4988-a4f4-35d9589b226b", - "is-owner": false - } - ] - ``` - -### 管理同步任务 (`changefeed`) - -#### 创建同步任务 - -使用以下命令来创建同步任务： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed create --pd=http://10.0.10.25:2379 --sink-uri="mysql://root:123456@127.0.0.1:3306/" -create changefeed ID: 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f info {"sink-uri":"mysql://root:123456@127.0.0.1:3306/","opts":{},"create-time":"2020-03-12T22:04:08.103600025+08:00","start-ts":415241823337054209,"target-ts":0,"admin-job-type":0,"config":{"filter-case-sensitive":false,"filter-rules":null,"ignore-txn-start-ts":null}} -``` - -其中 `--sink-uri` 需要按照以下格式进行配置，目前 scheme 支持 `mysql`/`tidb`/`kafka`。 - -{{< copyable "" >}} - -``` -[scheme]://[userinfo@][host]:[port][/path]?[query_parameters] -``` - -- Sink URI 配置 `mysql`/`tidb` - - 配置样例如下所示： - - {{< copyable "shell-regular" >}} - - ```shell - --sink-uri="mysql://root:123456@127.0.0.1:3306/?worker-count=16&max-txn-row=5000" - ``` - - 以上配置命令中的参数解析如下： - - | 参数 | 解析 | - | :------------ | :------------------------------------------------ | - | `root` | 下游数据库的用户名 | - | `123456` | 下游数据库密码 | - | `127.0.0.1` | 下游数据库的 IP | - | `3306` | 下游数据的连接端口 | - | `worker-count` | 向下游执行 SQL 的并发度（可选，默认值为 `16`） | - | `max-txn-row` | 向下游执行 SQL 的 batch 大小（可选，默认值为 `256`） | - -- Sink URI 配置 `kafka` - - 配置样例如下所示： - - {{< copyable "shell-regular" >}} - - ```shell - --sink-uri="kafka://127.0.0.1:9092/cdc-test?kafka-version=2.4.0&partition-num=6&max-message-bytes=67108864&replication-factor=1" - ``` - - 以上配置命令中的参数解析如下： - - | 参数 | 解析 | - | :------------------ | :------------------------------------------------------------ | - | `127.0.0.1` | 下游 Kafka 对外提供服务的 IP | - | `9092` | 下游 Kafka 的连接端口 | - | `cdc-test` | 使用的 Kafka topic 名字 | - | `kafka-version` | 下游 Kafka 版本号（可选，默认值 `2.4.0`） | - | `partition-num` | 下游 Kafka partition 数量（可选，不能大于实际 partition 数量。如果不填会自动获取 partition 数量。） | - | `max-message-bytes` | 每次向 Kafka broker 发送消息的最大数据量（可选，默认值 `64MB`） | - | `replication-factor` | kafka 消息保存副本数（可选，默认值 `1`） | - | `protocol` | 输出到 kafka 消息协议，可选值有 `default`, `canal`（默认值为 `default`） | - -如需设置更多同步任务的配置，比如指定同步单个数据表，请参阅[同步任务配置文件描述](#同步任务配置文件描述)。 - -使用配置文件创建同步任务的方法如下： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed create --pd=http://10.0.10.25:2379 --sink-uri="mysql://root:123456@127.0.0.1:3306/" --config changefeed.toml -``` - -其中 `changefeed.toml` 为同步任务的配置文件。 - -#### 查询同步任务列表 - -使用以下命令来查询同步任务列表： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed list --pd=http://10.0.10.25:2379 -``` - -``` -[ - { - "id": "28c43ffc-2316-4f4f-a70b-d1a7c59ba79f" - } -] -``` - -#### 查询特定同步任务 - -使用以下命令来查询特定同步任务（对应某个同步任务的信息和状态）： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed query --pd=http://10.0.10.25:2379 --changefeed-id=28c43ffc-2316-4f4f-a70b-d1a7c59ba79f -``` - -``` -{ - "info": { - "sink-uri": "mysql://root:123456@127.0.0.1:3306/", - "opts": {}, - "create-time": "2020-03-12T22:04:08.103600025+08:00", - "start-ts": 415241823337054209, - "target-ts": 0, - "admin-job-type": 0, - "config": { - "filter-case-sensitive": false, - "filter-rules": null, - "ignore-txn-start-ts": null - } - }, - "status": { - "resolved-ts": 415241860902289409, - "checkpoint-ts": 415241860640145409, - "admin-job-type": 0 - } -} -``` - -以上命令中： - -- `resolved-ts` 代表当前 changefeed 中最大的已经成功从 TiKV 发送到 TiCDC 的事务 TS； -- `checkpoint-ts` 代表当前 changefeed 中最大的已经成功写入下游的事务 TS； -- `admin-job-type` 代表一个 changefeed 的状态： - - `0`: 状态正常，也是初始状态。 - - `1`: 任务暂停。停止任务后所有同步 `processor` 会结束退出，同步任务的配置和同步状态都会保留，可以从 `checkpoint-ts` 恢复任务。 - - `2`: 任务恢复，同步任务从 `checkpoint-ts` 继续同步。 - - `3`: 任务已删除，接口请求后会结束所有同步 `processor`，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。 - -### 停止同步任务 - -使用以下命令来停止同步任务： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed pause --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f -``` - -以上命令中： - -- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 - -### 恢复同步任务 - -使用以下命令恢复同步任务： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed resume --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f -``` - -以上命令中： - -- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 - -### 删除同步任务 - -使用以下命令删除同步任务： - -{{< copyable "shell-regular" >}} - -```shell -cdc cli changefeed remove --pd=http://10.0.10.25:2379 --changefeed-id 28c43ffc-2316-4f4f-a70b-d1a7c59ba79f -``` - -- `--changefeed=uuid` 为需要操作的 `changefeed` ID。 - -### 管理同步子任务处理单元 (`processor`) - -- 查询 `processor` 列表： - - {{< copyable "shell-regular" >}} - - ```shell - cdc cli processor list --pd=http://10.0.10.25:2379 - ``` - - ``` - [ - { - "id": "9f84ff74-abf9-407f-a6e2-56aa35b33888", - "capture-id": "b293999a-4168-4988-a4f4-35d9589b226b", - "changefeed-id": "28c43ffc-2316-4f4f-a70b-d1a7c59ba79f" - } - ] - ``` - -- 查询特定 `processor`，对应于某个节点处理的同步子任务信息和状态： - - {{< copyable "shell-regular" >}} - - ```shell - cdc cli processor query --pd=http://10.0.10.25:2379 --changefeed-id=28c43ffc-2316-4f4f-a70b-d1a7c59ba79f --capture-id=b293999a-4168-4988-a4f4-35d9589b226b - ``` - - ``` - { - "status": { - "tables": { - "56": { # 56 表示同步表 id，对应 TiDB 中表的 tidb_table_id - "start-ts": 417474117955485702, - "mark-table-id": 0 # mark-table-id 是用于环形复制时标记表的 id，对应于 TiDB 中标记表的 tidb_table_id - } - }, - "operation": null, - "admin-job-type": 0 - }, - "position": { - "checkpoint-ts": 417474143881789441, - "resolved-ts": 417474143881789441, - "count": 0 - } - } - ``` - -以上命令中： - -- `status.tables` 中每一个作为 key 的数字代表同步表的 id，对应 TiDB 中表的 tidb_table_id； -- `mark-table-id` 是用于环形复制时标记表的 id，对应于 TiDB 中标记表的 tidb_table_id； -- `resolved-ts` 代表当前 processor 中已经排序数据的最大 TSO； -- `checkpoint-ts` 代表当前 processor 已经成功写入下游的事务的最大 TSO； - -## 使用 HTTP 接口管理集群状态和数据同步 - -目前 HTTP 接口提供一些基础的查询和运维功能。在以下接口描述中，假设 TiCDC server 的监听 IP 地址为 `127.0.0.1`，端口为 `8300`（在启动 TiCDC server 时通过 `--addr=ip:port` 指定绑定的 IP 和端口）。 - -### 获取 TiCDC server 状态信息的接口 - -使用以下命令获取 CDC server 状态信息的接口： - -{{< copyable "shell-regular" >}} - -```shell -curl http://127.0.0.1:8300/status -``` - -``` -{ - "version": "0.0.1", - "git_hash": "863f8ea889b144244ff53593a45c47ad22d37396", - "id": "6d92386a-73fc-43f3-89de-4e337a42b766", # capture id - "pid": 12102 # cdc server pid -} -``` - -### 驱逐 owner 节点 - -{{< copyable "shell-regular" >}} - -```shell -curl -X POST http://127.0.0.1:8300/capture/owner/resign -``` - -以上命令仅对 owner 节点请求有效。 - -``` -{ - "status": true, - "message": "" -} -``` - -{{< copyable "shell-regular" >}} - -```shell -curl -X POST http://127.0.0.1:8301/capture/owner/resign -``` - -以上命令对非 owner 节点请求返回错误。 - -``` -election: not leader -``` - -### 手动调度表到其他节点 - -{{< copyable "shell-regular" >}} - -```shell -curl -X POST curl 127.0.0.1:8300/capture/owner/move_table -X POST -d 'cf-id=cf060953-036c-4f31-899f-5afa0ad0c2f9&target-cp-id=6f19a6d9-0f8c-4dc9-b299-3ba7c0f216f5&table-id=49' -``` - -参数说明 - -| 参数名 | 说明 | -| :----------- | :--- | -| `cf-id` | 进行调度的 Changefeed ID | -| `target-cp-id` | 目标 Capture ID | -| `table-id` | 需要调度的 Table ID | - -以上命令仅对 owner 节点请求有效。对非 owner 节点将会返回错误。 - -``` -{ - "status": true, - "message": "" -} -``` - -## 同步任务配置文件描述 - -以下内容详细介绍了同步任务的配置。 - -```toml -# 指定配置文件中涉及的库名、表名是否为大小写敏感 -# 该配置会同时影响 filter 和 sink 相关配置，默认为 true -case-sensitive = true - -[filter] -# 忽略指定 start_ts 的事务 -ignore-txn-start-ts = [1, 2] - -# 过滤器规则 -# 过滤规则语法：https://github.com/pingcap/tidb-tools/tree/master/pkg/table-filter#syntax -rules = ['*.*', '!test.*'] - -[mounter] -# mounter 线程数，用于解码 TiKV 输出的数据 -worker-num = 16 - -[sink] -# 对于 MQ 类的 Sink，可以通过 dispatchers 配置 event 分发器 -# 支持 default、ts、rowid、table 四种分发器 -dispatchers = [ - {matcher = ['test1.*', 'test2.*'], dispatcher = "ts"}, - {matcher = ['test3.*', 'test4.*'], dispatcher = "rowid"}, -] -# 对于 MQ 类的 Sink，可以指定消息的协议格式 -# 目前支持 default 和 canal 两种协议。default 为 TiCDC Open Protocol -protocol = "default" - -[cyclic-replication] -# 是否开启环形同步 -enable = false -# 当前 TiCDC 的复制 ID -replica-id = 1 -# 需要过滤掉的同步 ID -filter-replica-ids = [2,3] -# 是否同步 DDL -sync-ddl = true -``` - -### 配置文件兼容性的注意事项 - -* TiCDC v4.0.0 中移除了 `ignore-txn-commit-ts`，添加了 `ignore-txn-start-ts`，使用 start_ts 过滤事务。 -* TiCDC v4.0.2 中移除了 `db-dbs`/`db-tables`/`ignore-dbs`/`ignore-tables`，添加了 `rules`，使用新版的数据库和数据表过滤规则，详细语法参考[表库过滤](/table-filter.md)。 - -## 环形同步 - -> **警告：** -> -> 目前环形同步属于实验特性，尚未经过完备的测试，不建议在生产环境中使用该功能。 - -环形同步功能支持在多个独立的 TiDB 集群间同步数据。比如有三个 TiDB 集群 A、B 和 C，它们都有一个数据表 `test.user_data`，并且各自对它有数据写入。环形同步功能可以将 A、B 和 C 对 `test.user_data` 的写入同步其它集群上，使三个集群上的 `test.user_data` 达到最终一致。 - -### 环形同步使用示例 - -在三个集群 A、B 和 C 上开启环形复制，其中 A 到 B 的同步使用两个 TiCDC。A 作为三个集群的 DDL 入口。 - -![TiCDC cyclic replication](/media/cdc-cyclic-replication.png) - -使用环形同步功能时，需要设置同步任务的创建参数： - -+ `--cyclic-replica-id`：用于指定为上游集群的写入指定来源 ID，需要确保每个集群 ID 的唯一性。 -+ `--cyclic-filter-replica-ids`：用于指定需要过滤的写入来源 ID，通常为下游集群的 ID。 -+ `--cyclic-sync-ddl`：用于指定是否同步 DDL 到下游，只能在一个集群的 CDC 上开启 DDL 同步。 - -环形同步任务创建步骤如下： - -1. 在 TiDB 集群 A，B 和 C 上[启动 TiCDC 组件](#ticdc-部署)。 - - {{< copyable "shell-regular" >}} - - ```shell - # 在 TiDB 集群 A 上启动 TiCDC 组件。 - cdc server \ - --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ - --log-file=ticdc_1.log \ - --addr=0.0.0.0:8301 \ - --advertise-addr=127.0.0.1:8301 - - # 在 TiDB 集群 B 上启动 TiCDC 组件。 - cdc server \ - --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ - --log-file=ticdc_2.log \ - --addr=0.0.0.0:8301 \ - --advertise-addr=127.0.0.1:8301 - - # 在 TiDB 集群 C 上启动 TiCDC 组件。 - cdc server \ - --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ - --log-file=ticdc_3.log \ - --addr=0.0.0.0:8301 \ - --advertise-addr=127.0.0.1:8301 - ``` - -2. 在 TiDB 集群 A，B 和 C 上创建环形同步需要使用的标记数据表 (`mark table`)。 - - {{< copyable "shell-regular" >}} - - ```shell - # 在 TiDB 集群 A 上创建标记数据表。 - cdc cli changefeed cyclic create-marktables \ - --cyclic-upstream-dsn="root@tcp(${TIDB_A_HOST}:${TIDB_A_PORT})/" \ - --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ - - # 在 TiDB 集群 B 上创建标记数据表。 - cdc cli changefeed cyclic create-marktables \ - --cyclic-upstream-dsn="root@tcp(${TIDB_B_HOST}:${TIDB_B_PORT})/" \ - --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ - - # 在 TiDB 集群 C 上创建标记数据表。 - cdc cli changefeed cyclic create-marktables \ - --cyclic-upstream-dsn="root@tcp(${TIDB_C_HOST}:${TIDB_C_PORT})/" \ - --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ - ``` - -3. 在 TiDB 集群 A，B 和 C 上创建环形同步任务。 - - {{< copyable "shell-regular" >}} - - ```shell - # 在 TiDB 集群 A 上创建环形同步任务。 - cdc cli changefeed create \ - --sink-uri="mysql://root@${TiDB_B_HOST}/" \ - --pd="http://${PD_A_HOST}:${PD_A_PORT}" \ - --cyclic-replica-id 1 \ - --cyclic-filter-replica-ids 2 \ - --cyclic-sync-ddl true - - # 在 TiDB 集群 B 上创建环形同步任务。 - cdc cli changefeed create \ - --sink-uri="mysql://root@${TiDB_C_HOST}/" \ - --pd="http://${PD_B_HOST}:${PD_B_PORT}" \ - --cyclic-replica-id 2 \ - --cyclic-filter-replica-ids 3 \ - --cyclic-sync-ddl true - - # 在 TiDB 集群 C 上创建环形同步任务。 - cdc cli changefeed create \ - --sink-uri="mysql://root@${TiDB_A_HOST}/" \ - --pd="http://${PD_C_HOST}:${PD_C_PORT}" \ - --cyclic-replica-id 3 \ - --cyclic-filter-replica-ids 1 \ - --cyclic-sync-ddl false - ``` - -### 环形同步使用限制 - -1. 在创建环形同步任务前，必须使用 `cdc cli changefeed cyclic create-marktables` 创建环形复制功能使用到的标记表。 -2. 开启环形复制的数据表只包含 [a-zA-z0-9_] 字符。 -3. 在创建环形同步任务前，开启环形复制的数据表必须已创建完毕。 -4. 开启环形复制后，不能创建一个会被环形同步任务同步的表。 -5. 如果想在线 DDL，需要确保以下两点： - 1. 多个集群的 CDC 构成一个单向 DDL 同步链，不能成环，例如示例中只有 C 集群的 CDC 关闭了 sync-ddl。 - 2. DDL 必须在单向 DDL 同步链的开始集群上执行，例如示例中的 A 集群。 diff --git a/tidb-lightning/tidb-lightning-configuration.md b/tidb-lightning/tidb-lightning-configuration.md index 82131a341e4c..b604527c6785 100644 --- a/tidb-lightning/tidb-lightning-configuration.md +++ b/tidb-lightning/tidb-lightning-configuration.md @@ -280,12 +280,8 @@ min-available-ratio = 0.05 | -V | 输出程序的版本 | | | -d *directory* | 读取数据的目录 | `mydumper.data-source-dir` | | -L *level* | 日志的等级： debug、info、warn、error 或 fatal (默认为 info) | `lightning.log-level` | -<<<<<<< HEAD -| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | -======= | -f *rule* | [表库过滤的规则](/table-filter.md) (可多次指定) | `mydumper.filter` | -| --backend *backend* | 选择后端的模式：`importer` `local` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | ->>>>>>> a4c0315... *: replace black-white-list by table filter (#3916) +| --backend *backend* | 选择后端的模式：`importer` 或 [`tidb`](/tidb-lightning/tidb-lightning-tidb-backend.md) | `tikv-importer.backend` | | --log-file *file* | 日志文件路径 | `lightning.log-file` | | --status-addr *ip:port* | TiDB Lightning 服务器的监听地址 | `lightning.status-port` | | --importer *host:port* | TiKV Importer 的地址 | `tikv-importer.addr` | From f5a2ae881152e1554cb24d57bf44190fe2cade7e Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 13 Jul 2020 12:09:04 +0800 Subject: [PATCH 3/4] fix a deadlink --- table-filter.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/table-filter.md b/table-filter.md index 378bef6e753e..8551b9168278 100644 --- a/table-filter.md +++ b/table-filter.md @@ -16,7 +16,7 @@ TiDB 生态工具默认情况下作用于所有数据库，但实际使用中， 在命令行中使用多个 `-f` 或 `--filter` 参数，即可在 TiDB 生态工具中应用表库过滤规则。每个过滤规则均采用 `db.table` 形式，支持通配符（详情见[下一节](#使用通配符)）。以下为各个工具中的使用示例： -* [Dumpling](/backup-and-restore-using-dumpling-lightning.md)： +* [Dumpling](/export-or-backup-using-dumpling.md)： {{< copyable "shell-regular" >}} From 0764fb6d9c520888c622404cec6ddf24660a6bcb Mon Sep 17 00:00:00 2001 From: Ran Date: Mon, 13 Jul 2020 14:12:08 +0800 Subject: [PATCH 4/4] Delete tidb-lightning-table-filter.md --- tidb-lightning/tidb-lightning-table-filter.md | 132 ------------------ 1 file changed, 132 deletions(-) delete mode 100644 tidb-lightning/tidb-lightning-table-filter.md diff --git a/tidb-lightning/tidb-lightning-table-filter.md b/tidb-lightning/tidb-lightning-table-filter.md deleted file mode 100644 index 7e6972ce55fd..000000000000 --- a/tidb-lightning/tidb-lightning-table-filter.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: TiDB Lightning 表库过滤 -summary: 使用黑白名单把一些表剔出要导入的范围。 -category: reference -aliases: ['/docs-cn/v3.0/reference/tools/tidb-lightning/table-filter/','/docs-cn/tools/lightning/filter/','/docs-cn/v3.0/reference/tools/tidb-lightning/filter/'] ---- - -# TiDB Lightning 表库过滤 - -TiDB Lightning 支持使用黑名单和白名单来过滤掉某些数据库和表。这可以用来跳过一些用作暂存、毋须迁移的表，或用来手动切分数据源，让多机同时导入。 - -这些过滤规则与 MySQL 的 `replication-rules-db`/`replication-rules-table` 类似。 - -## 过滤数据库 - -```toml -[black-white-list] -do-dbs = ["pattern1", "pattern2", "pattern3"] -ignore-dbs = ["pattern4", "pattern5"] -``` - -* 如果 `[black-white-list]` 下的 `do-dbs` 列表不为空， - * 如数据库名称匹配 `do-dbs` 列表中**任何**一项，则数据库会被导入。 - * 否则，数据库会被略过。 -* 否则，如果数据库名称匹配 `ignore-dbs` 列表中**任何**一项，数据库会被略过。 -* 如果数据库名称**同时**匹配 `do-dbs` 和 `ignore-dbs` 列表，数据库会被导入。 - -如果匹配项首字符为 `~`，它会被解析为 [Go 语言的正则表达式](https://golang.org/pkg/regexp/syntax/#hdr-syntax)。否则会视为普通的字串来匹配数据库名称。 - -> **注意：** -> -> 无论你如何设置过滤规则，系统数据库 `information_schema`、`performance_schema`、`mysql` 和 `sys` 总是会被略过。 - -## 过滤表 - -```toml -[[black-white-list.do-tables]] -db-name = "db-pattern-1" -tbl-name = "table-pattern-1" - -[[black-white-list.do-tables]] -db-name = "db-pattern-2" -tbl-name = "table-pattern-2" - -[[black-white-list.do-tables]] -db-name = "db-pattern-3" -tbl-name = "table-pattern-3" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-4" -tbl-name = "table-pattern-4" - -[[black-white-list.ignore-tables]] -db-name = "db-pattern-5" -tbl-name = "table-pattern-5" -``` - -* 如果 `do-tables` 列表不为空， - * 如果表的限定名称匹配 `do-tables` 列表中**任何**一对，则表会被导入。 - * 否则，表会被略过。 -* 否则，如果表的限定名称匹配 `ignore-tables` 列表中**任何**一对，表会被略过。 -* 如果表的限定名称**同时**匹配 `do-tables` 和 `ignore-tables` 列表，表会被导入。 - -> **注意：** -> -> Lightning 会先执行数据库过滤规则，之后才执行表的过滤规则。所以，如果一个数据库已被 `ignore-dbs` 略过，即使其下的表匹配 `do-tables` 也不会再被导入。 - -## 例子 - -以下例子演示过滤规则的操作原理。假设数据源包含这些表： - -``` -`logs`.`messages_2016` -`logs`.`messages_2017` -`logs`.`messages_2018` -`forum`.`users` -`forum`.`messages` -`forum_backup_2016`.`messages` -`forum_backup_2017`.`messages` -`forum_backup_2018`.`messages` -`admin`.`secrets` -``` - -我们使用以下设置： - -```toml -[black-white-list] -do-dbs = [ - "forum_backup_2018", # 规则 A - "~^(logs|forum)$", # 规则 B -] -ignore-dbs = [ - "~^forum_backup_", # 规则 C -] - -[[black-white-list.do-tables]] # 规则 D -db-name = "logs" -tbl-name = "~_2018$" - -[[black-white-list.ignore-tables]] # 规则 E -db-name = "~.*" -tbl-name = "~^messages.*" - -[[black-white-list.do-tables]] # 规则 F -db-name = "~^forum.*" -tbl-name = "messages" -``` - -首先进行数据库过滤： - -| 数据库 | 结果 | -|---------------------------|--------------| -| `` `logs` `` | 导入（规则 B） | -| `` `forum` `` | 导入（规则 B） | -| `` `forum_backup_2016` `` | 略过（规则 C） | -| `` `forum_backup_2017` `` | 略过（规则 C） | -| `` `forum_backup_2018` `` | 导入（规则 A）（不会考虑规则 C） | -| `` `admin` `` | 略过（`do-dbs` 不为空，且没有匹配的项目） | - -然后进行表过滤： - -| 表 | 结果 | -|--------------------------------------|--------------| -| `` `logs`.`messages_2016` `` | 略过（规则 E） | -| `` `logs`.`messages_2017` `` | 略过（规则 E） | -| `` `logs`.`messages_2018` `` | 导入（规则 D）（不会考虑规则 E） | -| `` `forum`.`users` `` | 略过（`do-tables` 不为空，且没有匹配的项目） | -| `` `forum`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `forum_backup_2016`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2017`.`messages` `` | 略过（数据库已被剔除） | -| `` `forum_backup_2018`.`messages` `` | 导入（规则 F）（不会考虑规则 E） | -| `` `admin`.`secrets` `` | 略过（数据库已被剔除） |