导入与迁移（兼容MongoDB语法）

步骤一：优化目标集群配置

为了提升全量数据导入的性能，建议在迁移前调整目标集群的写入批处理大小。

1. 连接到目标PolarDB PostgreSQL轻量版集群。

   # 将 localhost 替换为您的数据库主机IP
   PGPASSWORD=postgres /u01/polardb_pg/bin/psql -h localhost -p 1523 -U admin -d admin_db

   说明

   您可以通过查看配置文件postgresql.conf中的port参数来确认数据库的PostgreSQL协议端口。

2. 执行以下SQL命令，修改参数并使其生效。请确保使用具有superuser权限的账户（如admin）执行。

   ALTER SYSTEM SET documentdb.maxWriteBatchSize=100000;
   SELECT pg_reload_conf();

3. 执行SHOW documentdb.maxWriteBatchSize;命令，确认返回值为100000。

步骤二：启动dsync并开始迁移

dsync工具通过环境变量配置源和目标数据库的连接信息，启动后将自动执行全量和增量同步。

1. 设置环境变量，配置源和目标数据库的连接串（URI）。

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

   参数说明

   参数	说明
   src_username	源库账户，需具备root或readAnyDatabase权限。
   src_password	源库密码。
   src_ip	源库的主节点IP地址。
   src_port	源库的端口。
   src_db	需要迁移的源数据库名。
   dest_username	目标库账户，可使用admin等高权限账户。
   dest_password	目标库密码。
   dest_ip	目标库的IP地址。
   dest_port	目标库的MongoDB协议端口（默认为27030）。
   dest_db	迁移到目标库的数据库名。

   示例

   export MDB_SRC='mongodb://readAnyDatabase:password123@127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.0'
   export FERRETDB_DEST='mongodb://test_user:superuser_20250530@127.0.0.1:27030/postgres'

2. 启动dsync进程。建议使用--progress参数以可视化方式查看进度。

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

   参数说明

   字段	说明	样例
   Namespace	表示迁移的每个collection。	.ycsb.new_users：表示DB ycsb下的collection new_users。
   Percent Complete	表示完成进度。	100%，表示全量同步已经全部完成。
   Tasks Completed	表示全量迁移的切片任务情况。	5/21，表示21个任务完成了5个。
   Docs Synced	表示collections同步了多少行。	282132，表示同步了282132行。
   Throughput	表示吞吐：每秒同步了多少行。	-

   说明

   为防止因SSH会话中断导致迁移任务意外终止，强烈建议在tmux或screen等终端会话管理器中运行dsync命令。例如：

   tmux new -t mysession
   export MDB_SRC='mongodb://readAnyDatabase:password123@127.0.0.1:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.0'
   export FERRETDB_DEST='mongodb://test_user:superuser_20250530@127.0.0.1:27030/postgres'
   ./dsync --progress --logfile dsync.log "$MDB_SRC" "$FERRETDB_DEST"

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

步骤三：监控迁移进度

dsync启动后，您将在终端看到一个实时更新的进度报告，它会自动经历以下两个阶段：

1. 全量同步（InitialSync）

   此阶段会复制源数据库中的所有存量数据。您可以看到每个集合（Collection）的同步进度。

2. 增量同步（Change Stream） 全量同步完成后，dsync会自动进入增量同步阶段，持续捕获并应用源数据库中发生的数据变更（增、删、改）。

   

步骤四：（可选）数据校验

在准备进行业务切换前，您可以执行数据校验以确保源库和目标库的数据完全一致。

要执行全量数据校验，请先停止（Ctrl + C）正在运行的dsync进程，然后使用--verify参数重新启动：

# --verify 表示全量数据校验，注意校验命令需单独执行
./dsync --verify --progress --logfile dsync.log "$MDB_SRC" "$FERRETDB_DEST"

如果所有集合的校验结果均为OK，则表示数据完全一致。

步骤五：业务切换（Cutover）

当您确认数据同步完成并校验无误后，即可进行最后的业务切换。

1. 停止向源MongoDB实例写入数据（即停写业务应用）。

2. 观察dsync的增量同步界面，当Change Stream Events计数不再增长时，表示所有变更已同步至目标库。

3. 按下Ctrl + C停止dsync进程。

   重要

   在dsync进程完全退出之前，请勿关闭源MongoDB实例，否则可能导致同步状态丢失或报错。

4. 将您的应用程序的数据库连接配置修改为目标PolarDB PostgreSQL轻量版集群的连接串。

5. 启动业务应用，完成迁移。