使用DSync在线迁移MongoDB数据至PolarDB-云原生数据库PolarDB-阿里云

本指南为您提供了从社区MongoDB迁移至PolarDB PostgreSQL版详尽的操作步骤和最佳实践。PolarDB提供多种迁移工具，通过全量同步与增量同步相结合的方式，帮助您实现平滑、低停机时间的数据迁移。

迁移方案对比与决策

根据业务对停机时间、数据量、操作复杂度等要求，选择合适的迁移方案。

特性	在线迁移（使用DSync）	离线迁移（使用mongodump）
核心优势	支持增量数据同步，可将业务中断时间缩短至分钟级。	操作流程简单，无额外的迁移服务费用。
停机时间	分钟级。仅在最后进行业务切换时，需要短暂停止写入操作。	小时级或更长。停机时间取决于数据总量和网络带宽，整个迁移过程需要停止业务服务。
数据一致性	准实时同步，最终可确保源和目标数据库的数据完全一致。	迁移的数据是执行备份命令时间点的数据快照，不包含后续的增量数据。
适用场景	对业务连续性要求高的生产核心系统。	开发测试环境、可接受长时间停机窗口的业务，或仅需进行一次性全量数据迁移的场景。

采用DSync工具进行在线迁移

操作流程概览

准备环境与工具：获取DSync工具并准备好源和目标数据库的访问账号。
配置并启动迁移：创建环境变量，并启动迁移任务。
监控迁移进度：观察全量和增量同步的状态。
数据校验：确保源和目标数据库的数据一致。
业务切换：将应用流量切换至新的PolarDB集群。

步骤一：准备环境与工具

源库（MongoDB）：
- 需为副本集（Replica Set）或分片集群（Sharded Cluster）架构。
- 用于数据同步的连接节点需是主节点（Primary）。您可以通过rs.status()命令确认返回结果中连接节点的stateStr字段值是否为PRIMARY。
- 准备一个具有root或readAnyDatabase权限的数据库账号，供DSync工具读取数据。建议创建专用的迁移账户以遵循最小权限原则。
目标库（PolarDB）：
1. 已开启兼容文档数据库能力。
2. 获取文档数据库访问地址和PolarDB集群的高权限账号。
获取DSync工具：请提交工单联系我们获取DSync工具的RPM压缩包。
1. 安装：使用root权限执行以下命令安装。安装后，DSync工具默认安装在/u01/dsync/目录下。
```
sudo rpm -ivh t-polardb-pg-dsync-xxx.an8.x86_64.rpm
```
2. 验证安装：执行以下命令，如果返回版本号，则表示安装成功。
```
cd  /u01/dsync/
./dsync --version
```
  预期输出：
```
dsync version 0.15-beta (git commit dd1c8xxxx)
dsync exited successfully
```

优化目标集群性能：为提升全量数据导入性能，建议在迁移前临时调大目标集群的写入批处理大小documentdb.maxWriteBatchSize。此参数会增加目标库的内存消耗，建议迁移完成后将其恢复为默认值。

-- 查看并记录写入批处理默认值，在迁移完成后恢复至默认值。
SHOW documentdb.maxWriteBatchSize;

-- 调大参数值为100000
SET documentdb.maxWriteBatchSize = 100000;

-- 查看参数是否已修改。
SHOW documentdb.maxWriteBatchSize;

步骤二：配置并启动迁移任务

DSync工具提供自动化的Collection同步、全量数据同步与增量数据同步，仅需将DSync工具启动，数据同步即可自动进行。

设置环境变量：启动DSync工具仅需提供源库和目标库的连接串（URI）即可，这里通过环境变量的方式来设置参数，命令如下：

# 设置源库的连接串
export MDB_SRC='mongodb://<src_username>:<src_password>@<src_ip>:<src_port>/<src_db>'
# 设置目标库的连接串
export FERRETDB_DEST='mongodb://<dest_username>:<dest_password>@<dest_ip>:<dest_port>/<dest_db>'

参数说明

字段	说明
`src_username`	源库的账户权限需为`root`或`readAnyDatabase`，可通过执行`db.getUser("<src_username>")`进行确认。若输出结果包含`role: 'readWriteAnyDatabase'`或`role: 'root'`，则说明账户配置正确。
`src_password`	源库的密码。
`src_ip`	源库的连接地址。
`src_port`	源库的连接端口。
`src_db`	源库的数据库名。
`dest_username`	目标库的账户，可直接使用PolarDB PostgreSQL版集群的高权限账户。
`dest_password`	目标库的账户密码。
`dest_ip`	目标库的连接地址，即文档数据库访问地址。
`dest_port`	目标库的连接端口。
`dest_db`	目标库的数据库名。

示例

# 设置源库的连接串
export MDB_SRC='mongodb://root:YourPassword123!@dds-xxx.com:3717/admin'
# 设置目标库的连接串
export FERRETDB_DEST='mongodb://doc_user:YourPassword123!@pe-xxx.rwlb.rds.aliyuncs.com:5432'

启动迁移任务：推荐在前台启动，可查看可视化的进度。

# 使用配置文件启动，--progress 提供可视化进度，--logfile 记录详细日志
./dsync --progress --logfile dsync.log "$MDB_SRC" "$FERRETDB_DEST"

说明

为了避免会话超时导致DSync工具任务中断，建议采用tmux或者screen等会话管理工具，将dsync进程在tmux会话中执行，如下面的命令：

tmux new -t mysession

export MDB_SRC='mongodb://root:YourPassword123!@dds-xxx.com:3717/admin?serverSelectionTimeoutMS=2000&appName=mongosh+2.5.0'
export FERRETDB_DEST='mongodb://doc_user:YourPassword123!@pe-xxx.rwlb.rds.aliyuncs.com:5432'

./dsync --progress --logfile dsync.log "$MDB_SRC" "$FERRETDB_DEST"

假设已经通过tmux new -s mysession创建了，但窗口超时关闭了，可以通过tmux attach -t mysession命令重入。

步骤三：监控迁移进度

DSync工具在前台运行时提供可视化进度报告，分为两个阶段。

说明

Collection同步：默认会将所有db下的所有Collection进行同步。

全量同步阶段（Dsync Progress Report : InitialSync）：此阶段显示存量数据的迁移进度。
增量同步阶段（Dsync Progress Report : ChangeStream）：全量同步完成后，DSync工具自动切换到此阶段，持续同步数据变更。

进度指标含义

字段	含义	说明
`Namespace`	迁移对象	当前迁移的数据库和集合（`db.collection`）。
`Percent Complete`	完成进度	全量同步阶段的完成百分比，100%表示全量同步已经全部完成。
`Tasks Completed`	任务切片	全量迁移被切分为多个任务，显示已完成的任务数与总任务数。
`Docs Synced`	同步文档数	已同步的文档（行）总数。
`Throughput`	吞吐量	每秒同步的文档数，反映当前迁移速度。
`Change Stream Events`	增量事件数	增量同步阶段已捕获并处理的数据变更事件数量。

步骤四：数据校验

数据校验是确保迁移质量的环节。在进行增量同步结束完、且不会再有增量的情况下，可以对源库和目标库进行校验。

（快速抽样）基础校验：在源库和目标库中，使用db.xxx.countDocuments({})命令检查文档数量是否一致。此方法适用于快速评估。
（推荐）完整性校验：DSync工具提供--verify参数用于全量数据比对，确保数据内容一致。
说明
执行--verify前，需先停止DSync工具的同步进程，并确保源库无新的数据写入（例如停止实例或应用）。此操作会执行全表扫描，消耗较多资源且耗时较长。
```
# --verify 表示全量数据校验，注意校验命令需单独执行
./dsync --verify --progress --logfile dsync.log "$MDB_SRC" "$FERRETDB_DEST"
```
当所有集合的校验结果均为OK时，表示数据内容一致。

步骤五：业务切换与回滚

业务切换是迁移流程的最后一步，需严格按照预案执行。

参考切换步骤

停止应用写入：在计划的切换时间窗口，停止所有应用对源MongoDB数据库的写入操作。
确认增量同步追平：观察DSync工具的监控界面，等待Change Stream Events的数值停止增长，表示所有变更数据均已同步至目标库。
停止DSync：确认增量同步完成后，在会话中停止DSync工具进程。DSync工具会在完成清理工作后正常退出。
说明
需在DSync工具进程正常结束后，才能停止源库，否则DSync工具会报错。
（可选）最终数据校验：再次执行文档数量校验，作为最后保障。
切换应用连接：将应用程序的数据库连接配置从源MongoDB数据库切换到目标PolarDB集群。
启动并验证业务：重启应用服务，对核心业务功能进行回归测试，确保读写操作正常。

回滚预案

如果在切换后发现问题（如核心功能异常、数据不一致等），应立即启动回滚方案恢复业务：

切回源库：将应用程序的数据库连接配置改回源源MongoDB数据库。
重启应用：重启应用服务，将业务流量切回源数据库。
问题排查：业务恢复后，离线排查迁移过程中出现的问题，并在下一个维护窗口重新规划迁移。

使用mongodump/mongorestore进行离线迁移

此方法通过MongoDB官方工具进行全量备份和恢复，适用于可接受较长停机时间的场景。

步骤一：备份源端数据（mongodump）

在可连接到源MongoDB的服务器上，执行mongodump命令，从源MongoDB数据库创建全量数据备份。建议添加以下参数：

--uri：指定源数据库的连接字符串。
--oplog：在备份期间记录oplog，确保备份数据的一致性。
--out：指定备份文件的输出目录。

# 示例命令
mongodump --uri="mongodb://<username>:<password>@<source_ip>:<source_port>/<source_db>" --oplog --out /path/to/backup_dir/

说明

执行备份操作可能对源库性能产生影响，建议在业务低峰期进行。确保备份目录所在磁盘有足够空间。

步骤二：恢复数据至目标端（mongorestore）

将备份文件目录传输到可连接目标PolarDB集群的服务器上，然后执行mongorestore命令，将备份数据导入目标PolarDB集群。

# 推荐：省略密码，交互式输入
mongorestore --uri="mongodb://<username>@<polardb_endpoint>:<port>/<dest_db>" /path/to/backup_dir/

<username>：在PolarDB集群中创建的文档数据库专用账号。
<polardb_endpoint>:<port>：PolarDB集群的文档数据库兼容地址和端口。

说明

为避免密码在命令行历史或进程列表中泄露，建议不在--uri参数中直接提供密码。执行命令后，系统会提示交互式的输入密码。

步骤三：验证数据

确认数据已完整与准确地恢复到目标数据库。连接到目标PolarDB集群，执行以下检查：

检查集合数量：确认所有预期的集合都已创建。
抽样检查文档内容：随机抽取几条文档，对比其内容是否与源端一致。

常见问题

dsync迁移时需要手动在目标库创建集合（Collection）吗？

不需要。dsync会自动在目标库创建源数据库中的所有集合，并同步其索引和数据。

dsync迁移过程中，如果源库或目标库发生重启会怎么样？

目标库重启：无影响。dsync会记录同步断点，待目标库恢复后，会自动从断点处继续同步，不会丢失数据。
源库重启：dsync会尝试重连。如果源库停机时间过长，导致其oplog被覆盖，dsync将无法继续增量同步并退出。此时，您需要在源库恢复后，重新启动dsync进程进行迁移。