RawKV CDC 使用手册

如何使用 RawKV Change Data Capture

本文是 RawKV CDC 的使用手册。

RawKV CDC 使用手册

部署

支持 RawKV CDC 的最小 TiKV 版本为 v6.2.0，并打开 TiKV API V2

使用 TiUP 部署

支持 TiKV-CDC 的最小 TiUP 版本为 v1.11.0

使用 TiUP 部署包含 TiKV-CDC 组件的全新 TiKV 集群

在使用 TiUP 部署全新的 TiKV 集群时，支持同时部署 TiKV-CDC 组件。只需在 TiUP 的拓扑配置中加入 TiKV-CDC 部分即可。可参考模板。

使用 TiUP 在现有 TiKV 集群上新增 TiKV-CDC 组件

目前也支持在现有的 TiKV 集群上使用 TiUP 新增 TiKV-CDC 组件，操作步骤如下：

确认当前 TiKV 集群的版本 >= v6.2.0，并且已打开 TiKV API V2。
根据模板创建扩容配置文件。
通过 tiup cluster scale-out 扩容 TiKV-CDC 组件（TiUP 扩容可参考使用 TiUP 扩容缩容 TiDB 集群）。

tiup cluster scale-out <cluster-name> scale-out.yaml

手工部署

部署两个 TiKV 集群，分别作为上游集群和下游集群。
启动 TiKV-CDC 集群，可包含一个或多个 TiKV-CDC server。TiKV-CDC server 的启动命令是 tikv-cdc server --pd <upstream PD endpoints>。
通过以下命令启动同步任务：tikv-cdc cli changefeed create --pd <upstream PD endpoints> --sink-uri tikv://<downstream PD endpoints>。

TiKV-CDC server 启动参数

addr：TiKV-CDC 的监听地址，用于提供 HTTP API 和 Prometheus 查询，默认为 127.0.0.1:8600。
advertise-addr：TiKV-CDC 供客户端访问的外部开放地址。如果未设置，默认与 addr 相同。
pd：TiKV-CDC 监听的 PD 节点地址，多个地址用英文逗号（,）分隔。
config：可选项，指定 TiKV-CDC 使用的配置文件路径。
data-dir：可选项，指定 TiKV-CDC 存储运行时数据的目录，主要用于外部排序。建议确保该目录所在设备的可用空间大于等于 500 GiB。
gc-ttl：可选项，TiKV-CDC 在 PD 设置服务级别 GC safepoint 的 TTL (Time To Live) 时长。同时也是 TiKV-CDC 同步任务暂停的最大时长。单位为秒，默认值为 86400，即 24 小时。注意：TiKV-CDC 同步任务的暂停会影响集群 GC safepoint 的推进。gc-ttl 越大，同步任务可以暂停的时间越长，但同时需要保留更多的过期数据、并占用更多的存储空间。反之亦然。
log-file：可选项，TiKV-CDC 进程运行时日志的输出路径，未设置时默认为标准输出 (stdout)。
log-level：可选项，TiKV-CDC 进程运行时的日志路径，默认为 info。
ca：可选项，指定用于 TLS 连接的 CA 证书文件路径。仅支持 PEM 格式。
cert：可选项，指定用于 TLS 连接的证书文件路径。仅支持 PEM 格式。
key：可选项，指定用于 TLS 连接的私钥文件路径。仅支持 PEM 格式。
cert-allowed-cn：可选项，指定允许的调用者标识（即证书 Common Name，CN）。多个 CN 用英文逗号（,）分隔。

运维管理

必备条件

运维管理需要使用 tikv-cdc 二进制可执行文件。Linux x86-64 下的二进制可执行文件可以通过 TiUP 获取（如下所示），或者从 releases 页面下载。其他平台需要从源代码编译。

tiup install tikv-cdc
tiup tikv-cdc cli --help

管理 TiKV-CDC 服务进程 (`capture`)

查询 `capture` 列表

tikv-cdc cli capture list --pd=http://192.168.100.122:2379

[
  {
    "id": "07684765-52df-42a0-8dd1-a4e9084bb7c1",
    "is-owner": false,
    "address": "192.168.100.9:8600"
  },
  {
    "id": "aea1445b-c065-4dc5-be53-a445261f7fc2",
    "is-owner": true,
    "address": "192.168.100.26:8600"
  },
  {
    "id": "f29496df-f6b4-4c1e-bfa3-41a058ce2144",
    "is-owner": false,
    "address": "192.168.100.142:8600"
  }
]

在以上结果中：

id：服务进程的 ID。
is-owner：表示该服务进程是否为 owner 节点。
address：该服务进程对外提供接口的地址。

如果要求使用 TLS 连接：

tikv-cdc cli capture list --pd=http://192.168.100.122:2379 --ca=$TLS_DIR/ca.pem --cert=$TLS_DIR/client.pem --key=$TLS_DIR/client-key.pem

在以上命令中：

ca：指定 CA 证书文件路径。仅支持 PEM 格式。
cert：指定证书文件路径。仅支持 PEM 格式。
key：指定私钥文件路径。仅支持 PEM 格式。

管理同步任务 (`changefeed`)

创建同步任务

tikv-cdc cli changefeed create --pd=http://192.168.100.122:2379 --sink-uri="tikv://192.168.100.61:2379/" --changefeed-id="rawkv-replication-task" --config="changefeed.toml"

Create changefeed successfully!
ID: rawkv-replication-task
Info: {"sink-uri":"tikv://192.168.100.61:2379","opts":{},"create-time":"2022-07-20T15:35:47.860947953+08:00","start-ts":434714063103852547,"target-ts":0,"admin-job-type":0,"sort-engine":"unified","sort-dir":"","scheduler":{"type":"keyspan-number","polling-time":-1},"state":"normal","history":null,"error":null}

在以上命令和结果中：

--changefeed-id：同步任务的 ID，格式需要符合正则表达式 ^[a-zA-Z0-9]+(\-[a-zA-Z0-9]+)*$。如果不指定该 ID，TiKV-CDC 会自动生成一个 UUID（version 4 格式）作为 ID。
--sink-uri：同步任务下游的地址，需要按照以下格式进行配置。目前 scheme 仅支持 tikv。此外，如果 URI 中包含特殊字符，需要以 URL 编码对特殊字符进行处理。

[scheme]://[userinfo@][host]:[port][/path]?[query_parameters]

--start-ts：指定 changefeed 的开始 TSO。TiKV-CDC 集群将从这个 TSO 开始拉取数据。默认为当前时间。

如果需要将现有集群中的存量数据同步到下游，请参考如何同步 TiKV 集群中的存量数据。

--config: 指定 changefeed 配置文件。请参考 changefeed 配置文件。

Sink URI 配置 `tikv`

--sink-uri="tikv://192.168.100.61:2379/"

参数	说明
192.168.100.61:2379	下游 PD 地址。多个地址用英文逗号（`,`）分隔。

如果要求使用 TLS 连接：

--sink-uri="tikv://192.168.100.61:2379/?ca-path=$TLS_DIR/ca.pem&cert-path=$TLS_DIR/client.pem&key-path=$TLS_DIR/client-key.pem"

参数	说明
192.168.100.61:2379	下游 PD 地址。多个地址用英文逗号（`,`）分隔。
ca-path	CA 证书文件路径，仅支持 PEM 格式。
cert-path	证书文件路径，仅支持 PEM 格式。
key-path	私钥文件路径，仅支持 PEM 格式

Changefeed 配置文件

本部分详细介绍了 changefeed 的配置。

# 是否使用过滤器，从 v1.2.0 开始支持。使用规则如下：
#
# 1. 当数据匹配过滤器中配置的全部规则时，才会复制到下游。其余数据将被丢弃。
# 2. 当不需要使用某个规则时，不填写该字段或者配置为空值（""）。
# 3. 过滤器中的多个规则为“与”关系。
# 4. 可以通过 "\x" 输入二进制数据，例如："\x00\x01\xff"，表示 0x00, 0x01, 0xff。
# 5. 正则表达式语法参考：https://github.com/google/re2/wiki/Syntax。
# 6. 删除操作忽略 value-pattern 规则，只能通过 key-prefix 或 key-pattern 进行过滤。
[filter]
# 指定 key 的前缀
key-prefix = "prefix"

# 指定 key 需要匹配的正则表达式
key-pattern = "k_[\x00-\xff]"

# 指定 value 需要匹配的正则表达式
value-pattern = "v_.{8}"

查询同步任务列表

tikv-cdc cli changefeed list --pd=http://192.168.100.122:2379

[
  {
    "id": "rawkv-replication-task",
    "summary": {
      "state": "normal",
      "tso": 434715745556889877,
      "checkpoint": "2022-07-20 17:22:45.900",
      "error": null
    }
  }
]

在以上结果中：

checkpoint 表示 TiKV-CDC 已经将该时间点前的数据同步到了下游。
state 为该同步任务的状态：
- normal：正常同步
- stopped：停止同步（手动暂停）
- error：停止同步（出错）
- removed：已删除任务（只在指定 –all 选项时才会显示该状态的任务）

查询特定同步任务

tikv-cdc cli changefeed query -s --changefeed-id rawkv-replication-task --pd=http://192.168.100.122:2379

{
 "state": "normal",
 "tso": 434716089136185435,
 "checkpoint": "2022-07-20 17:44:36.551",
 "error": null
}

在以上命令和结果中：

-s 代表仅返回简化后的同步状态。
state 代表当前 changefeed 的同步状态，与 changefeed list 中的状态相同。
tso 代表当前 changefeed 中已经成功写入下游的最大 TSO。
checkpoint 代表当前 changefeed 中已经成功写入下游的最大 TSO 对应的时间。
error 记录当前 changefeed 是否有错误发生。

tikv-cdc cli changefeed query --changefeed-id rawkv-replication-task --pd=http://192.168.100.122:2379

{
  "info": {
    "sink-uri": "tikv://192.168.100.61:2379/",
    "opts": {},
    "create-time": "2022-07-20T17:21:54.115625346+08:00",
    "start-ts": 434715731964985345,
    "target-ts": 0,
    "admin-job-type": 0,
    "sort-engine": "unified",
    "sort-dir": "",
    "config": {
      "check-gc-safe-point": true,
      "scheduler": {
        "type": "keyspan-number",
        "polling-time": -1
      },
    },
    "state": "normal",
    "history": null,
    "error": null,
    "sync-point-enabled": false,
    "sync-point-interval": 600000000000,
  },
  "status": {
    "resolved-ts": 434715754364928912,
    "checkpoint-ts": 434715754103047044,
    "admin-job-type": 0
  },
  "count": 0,
  "task-status": [
    {
      "capture-id": "aea1445b-c065-4dc5-be53-a445261f7fc2",
      "status": {
        "keyspans": {
          "15137828009456710810": {
            "start-ts": 434715731964985345,
            "Start": "cg==",
            "End": "cw=="
          }
        },
        "operation": {},
        "admin-job-type": 0
      }
    }
  ]
}

在以上结果中：

info：代表当前 changefeed 的同步配置。
status：代表当前 changefeed 的同步状态信息。
resolved-ts：代表当前 changefeed 从上游 TiKV 接收到的最大水位线（watermark）。水位线是一个时间戳，表示所有早于这个时间戳的 RawKV 数据，都已经从上游 TiKV 接收到了。
checkpoint-ts：代表当前 changefeed 中已经成功写入下游的最大水位线（watermark）。这个水位线表示所有早于这个时间戳的 RawKV 数据，都已经成功写入下游 TiKV。
admin-job-type：代表当前 changefeed 的状态：
- 0：状态正常。
- 1：任务暂停，停止任务后所有同步 processor 会结束退出，同步任务的配置和同步状态都会保留，可以从 checkpoint-ts 恢复任务。
- 2：任务恢复，同步任务从 checkpoint-ts 继续同步。
- 3：任务已删除，所有同步 processor 结束退出，并清理同步任务配置信息。同步状态保留，只提供查询，没有其他实际功能。
task-status 代表当前 changefeed 所分配的各个同步子任务的状态信息。

停止同步任务

tikv-cdc cli changefeed pause --changefeed-id rawkv-replication-task --pd=http://192.168.100.122:2379
tikv-cdc cli changefeed list --pd=http://192.168.100.122:2379

[
  {
    "id": "rawkv-replication-task",
    "summary": {
      "state": "stopped",
      "tso": 434715759083521004,
      "checkpoint": "2022-07-20 17:23:37.500",
      "error": null
    }
  }
]

在以上命令中：

--changefeed-id=uuid 为需要操作的 changefeed ID。

恢复同步任务

tikv-cdc cli changefeed resume --changefeed-id rawkv-replication-task --pd=http://192.168.100.122:2379
tikv-cdc cli changefeed list --pd=http://192.168.100.122:2379

[
  {
    "id": "rawkv-replication-task",
    "summary": {
      "state": "normal",
      "tso": 434715759083521004,
      "checkpoint": "2022-07-20 17:23:37.500",
      "error": null
    }
  }
]

删除同步任务

tikv-cdc cli changefeed remove --changefeed-id rawkv-replication-task --pd=http://192.168.100.122:2379
tikv-cdc cli changefeed list --pd=http://192.168.100.122:2379

[]

查询同步子任务处理单元 (processor)

tikv-cdc cli processor list --pd=http://192.168.100.122:2379`

[
  {
    "changefeed_id": "rawkv-replication-task",
    "capture_id": "07684765-52df-42a0-8dd1-a4e9084bb7c1"
  }
]

常见问题

如何同步现有 TiKV 集群中的存量数据

首先通过 TiKV-BR 将存量数据复制到下游（需要部署 NFS、S3 等网络共享存储），然后创建 changefeed 进行后续的增量数据同步。

不建议使用 TiKV-CDC 直接同步存量数据，原因包括：

TiKV 集群垃圾回收的生命期（life time）较短（默认为 10 分钟），因此在大部分情况下，直接进行同步是不可行的。Changefeed 的 start-ts 不可小于 GC Safe Point。
如果存量数据较大，通过 TiKV-CDC 同步较为低效，因为所有的存量数据都需要首先拉取并暂存在 TiKV-CDC 中，然后按时间戳大小排序，才能最后写入下游集群。相比之下，TiKV-BR 可以充分利用整个 TiKV 集群的资源，因为在备份和恢复的过程中，每个 region 直接向共享存储导出或者导入数据，并且不需要排序。

同步存量数据的步骤：

通过 TiKV-BR 备份上游集群数据，并指定足够长的 --gcttl 参数。参考备份 Raw 模式数据。

注意：--gcttl 需要包括数据备份时长、数据恢复时长、以及其他准备工作的时长。如果无法预计这些时长，可以临时停止 GC（SET GLOBAL tidb_gc_enable = "OFF";，见 tidb_gc_enable），并在 changefeed 启动后恢复（SET GLOBAL tidb_gc_enable = "ON";）。

记录步骤 1 备份结果中的 backup-ts。
将备份数据恢复到下游集群。参考恢复 Raw 模式数据。
创建 changefeed，并指定 --start-ts=<backup-ts>。

RawKV CDC 使用手册

如何使用 RawKV Change Data Capture