教程：使用 MongoDB 本机工具借助离线方式将 MongoDB 迁移到 Azure Cosmos DB 的 MongoDB API

适用对象： Mongodb

此 MongoDB 迁移指南是有关 MongoDB 迁移的系列教程的一部分。 关键的 MongoDB 迁移步骤是 迁移前、迁移和 迁移后，如下图所示。

使用 MongoDB 原生工具迁移数据概述

可以使用 MongoDB 本机工具将数据库从 MongoDB 的本地或云实例脱机（一次性）迁移到 Azure Cosmos DB 的用于 MongoDB 的 API。

在本教程中，你将了解如何执行以下操作：

在本教程中，将使用 MongoDB 本机工具将托管在 Azure 虚拟机中的 MongoDB 中的数据集迁移到用于 MongoDB 的 Azure Cosmos DB API。 MongoDB 本机工具是一组二进制文件，有助于对现有 MongoDB 实例进行数据操作。 由于Azure Cosmos DB公开用于 MongoDB 的 API，因此 MongoDB 本机工具可以将数据插入Azure Cosmos DB。 本文的重点是使用 mongoexport/mongoimport 或mongodump/mongorestore 将数据从 MongoDB 实例中迁移出来。 由于本机工具使用连接字符串连接到 MongoDB，因此可以在任意位置运行这些工具，但我们建议在与 MongoDB 实例相同的网络中运行这些工具，以避免防火墙问题。

MongoDB 本机工具只能以主机硬件允许的速度移动数据。 原生工具可以是处理小型数据集的最简单解决方案，因为在这种情况下，总迁移时间不太重要。 如果需要可缩放的迁移管道，那么 MongoDB Spark 连接器、Azure 数据迁移服务 (DMS) 或 Azure 数据工厂 (ADF) 可能是更好的选择。

如果尚未设置 MongoDB 源，请参阅在 Azure 中的 Windows VM 上安装和配置 MongoDB 一文。

先决条件

要完成本教程，需要：

• 完成迁移前步骤，例如估计吞吐量、选择分区键和索引策略。
• 创建 Azure Cosmos DB for MongoDB 帐户。
• 登录到 MongoDB 实例。
  • 从此链接下载并安装 MongoDB 本机工具。
    • 请确保你的 MongoDB 本机工具版本与现有的 MongoDB 实例匹配。
    • 如果 MongoDB 实例的版本与 Azure Cosmos DB for MongoDB 的版本不同，则请安装这两个 MongoDB 本机工具版本，并分别为 MongoDB 和 Azure Cosmos DB for MongoDB 使用适当的工具版本。
  • 添加具有 readWrite 权限的用户，除非已存在这样的用户。 在本教程的后面部分，请向 mongoexport 和 mongodump 工具提供此用户名和密码。

配置 Azure Cosmos DB 服务器端重试

从 MongoDB 迁移到 Azure Cosmos DB 时，可以从资源治理功能中受益，这些功能保证能够充分利用预配的 RU/s 吞吐量。 如果某个请求超过了容器预配的 RU/s，Azure Cosmos DB 可能会在迁移期间对该请求进行限流。 该请求需要重试。 迁移工具与Azure Cosmos DB之间的网络跃点所涉及的往返时间会影响该请求的总体响应时间。 此外，MongoDB 本机工具可能无法处理重试。 Azure Cosmos DB的服务器端重试功能使服务能够截获限制错误代码，并重试往返时间要低得多，这大大提高了请求响应时间。 从 MongoDB 本机工具的角度来看，需要处理重试的需求会最小化，这会对迁移期间的体验产生积极影响。

服务器端重试功能位于Azure Cosmos DB门户的“功能”边栏选项卡中。

如果它 已禁用，建议启用它，如以下屏幕截图所示。

选择适当的 MongoDB 本机工具

• mongoexport/mongoimport 是迁移 MongoDB 数据库子集的最佳迁移工具组合。
  • mongoexport 将现有的数据导出为可读的 JSON 或 CSV 文件。 mongoexport 接受一个参数，用于指定要导出的现有数据子集。
  • mongoimport 打开 JSON 或 CSV 文件，并将内容插入目标数据库实例（在本例中Azure Cosmos DB）。
  • 请注意，JSON 和 CSV 不是压缩格式。 当 mongoimport 将数据发送到Azure Cosmos DB时，可能会产生过多的网络费用。
• mongodump/mongorestore 是迁移整个 MongoDB 数据库的最佳迁移工具组合。 压缩的 BSON 格式可以更高效地使用网络资源，因为数据插入Azure Cosmos DB。
  • mongodump 会将现有数据导出为 BSON 文件。
  • mongorestore 会将您的 BSON 文件转储导入 Azure Cosmos DB。
• 如果你有一个想要导入 Azure Cosmos DB for MongoDB 的小型 JSON 文件，mongoimport 工具是一种快速的解决方案。

获取 Azure Cosmos DB 的 MongoDB 凭据

Azure Cosmos DB for MongoDB 提供 MongoDB 本机工具可以使用的兼容访问凭据。 需要这些访问凭据才能将数据迁移到用于 MongoDB 的 Azure Cosmos DB。 要查找这些凭证，请执行以下操作：

1. 打开 Azure 门户。

2. 转到你的用于 MongoDB 的 Azure Cosmos DB 帐户。

3. 在左侧导航中，选择 “连接字符串 ”边栏选项卡。 你将看到如下所示的内容：

   

   • HOST - Azure Cosmos DB 终结点充当 MongoDB 主机名
   • PORT - MongoDB 原生工具连接到 Azure Cosmos DB 时，必须显式指定此端口
   • 在 Azure Cosmos DB 的端点域名中，USERNAME 前缀将作为 MongoDB 用户名使用。
   • PASSWORD - Azure Cosmos DB 主密钥充当 MongoDB 密码
   • 另外，请注意 SSL 字段，其值为 true——MongoDB 原生工具在将数据写入 Azure Cosmos DB 时必须启用 SSL

执行迁移

1. 选择要迁移的数据库和集合。 在此示例中，将 edx 数据库中的查询集合从 MongoDB 迁移到 Azure Cosmos DB。

本节其余内容将引导你使用你在上一节中选择的那对工具。

mongoexport/mongoimport

1. 若要从源 MongoDB 实例导出数据，请在 MongoDB 实例计算机上打开一个终端。 如果是 Linux 计算机，请键入以下命令：

   mongoexport --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db edx --collection query --out edx.json
   

   在Windows上，可执行文件为 mongoexport.exe. 根据现有 MongoDB 数据库实例的属性填写 HOST、 PORT、 USERNAME 和 PASSWORD 。

   还可以选择仅导出 MongoDB 数据集的子集。 导出子集的一种方法是添加筛选器参数：

   mongoexport --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db edx --collection query --out edx.json --query '{"field1":"value1"}'
   

   仅导出与筛选器 {"field1":"value1"} 匹配的文档。

   运行命令时，会看到它创建一个 edx.json 文件：

   

2. 可以使用同一终端将 edx.json 导入 Azure Cosmos DB。 如果在 Linux 计算机上运行 mongoimport ，请键入以下命令：

   mongoimport --host HOST:PORT -u USERNAME -p PASSWORD --db edx --collection importedQuery --ssl --type json --writeConcern="{w:0}" --file edx.json
   

   在Windows上，mongoimport.exe是可执行文件。 使用之前收集的Azure Cosmos DB凭据填写主机、端口、用户名和密码。

3. 对 mongoimport 的终端输出进行监控。 应会看到它在终端上打印了文本行，其中包含有关迁移状态的更新：

   

4. 最后，检查 Azure Cosmos DB，验证迁移是否成功。 打开Azure Cosmos DB门户并转到数据资源管理器。 应会看到已创建具有 importedQuery 集合的 edx 数据库，如果只导出了一部分数据，importedQuery仅包含与所需数据子集匹配的文档。 在以下示例中，只有一个文档与筛选器 {"field1":"value1"}匹配：

   

mongodump/mongorestore

1. 若要创建 MongoDB 实例的 BSON 数据转储，请在 MongoDB 实例计算机上打开一个终端。 如果是 Linux 计算机，请键入

   mongodump --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db edx --collection query --ssl --out edx-dump
   

   应根据现有 MongoDB 数据库实例的属性填写 HOST、PORT、USERNAME 和 PASSWORD 。 应会看到生成了 edx-dump 目录，并且 edx-dump 的目录结构再现了源 MongoDB 实例的资源层次结构（数据库和集合结构）。 每个集合都由一个 BSON 文件表示：

   

2. 可以使用同一终端将 edx-dump 的内容还原到 Azure Cosmos DB 中。 如果在 Linux 计算机上运行 mongorestore ，请键入以下命令：

   mongorestore --host HOST:PORT --authenticationDatabase admin -u USERNAME -p PASSWORD --db edx --collection importedQuery --writeConcern="{w:0}" --ssl edx-dump/edx/query.bson
   

   在Windows上，可执行文件为 mongorestore.exe. 将 HOST、PORT、USERNAME 和 PASSWORD 替换为之前收集的Azure Cosmos DB凭据。

3. 监控 mongorestore 的终端输出。 应会看到它在终端上打印行，用于显示迁移状态更新：

   

4. 最后，检查 Azure Cosmos DB，验证迁移是否成功。 打开 Azure Cosmos DB 门户，并导航到“数据资源管理器”。 你应该会看到，已创建了一个包含 importedQuery 集合的 edx 数据库，并且 importedQuery 应包含源集合中的整个数据集：

   

迁移后优化

将 MongoDB 数据库中存储的数据迁移到 Azure Cosmos DB 的 API for MongoDB 后，你可以连接到 Azure Cosmos DB 并管理数据。 还可以执行其他迁移后优化步骤，例如优化索引策略、更新默认一致性级别或为Azure Cosmos DB帐户配置多区域分发。 有关详细信息，请参阅迁移后优化一文。

其他资源

• Azure Cosmos DB 服务信息
• MongoDB 数据库工具文档
• 尝试为迁移到 Azure Cosmos DB 进行容量规划？
  • 如果仅知道现有数据库群集中的 vcore 数和服务器数，请阅读有关使用 vCore 或 vCPU 估算请求单位的信息
  • 若知道当前数据库工作负载的典型请求速率，请阅读使用 Azure Cosmos DB 容量计划工具估算请求单位

后续步骤

• 在 Azure 数据库迁移指南中查看用于其他场景的迁移指南。