/ /

`start`

说明

启动源集群和目标集群之间的同步。

要求

州

要使用start端点， mongosync必须处于IDLE状态。

权限

mongosync 连接string中指定的用户必须对源集群和目标集群具有所需的权限。请参阅用户权限，确保用户具有启动同步的正确权限。

多个 `mongosync` 实例

确保在启动mongosync时，使用在cluster0或cluster1设置的连接字符串中配置的mongosync用户。

注意

当您配置多个mongosync实例在分片集群之间同步时，您必须向每个mongosync实例发送相同的 API 端点命令。

有关更多信息，请参阅启动多个 Mongosync。

请求

POST /api/v1/start

请求正文参数

Parameter

类型

必要性

说明

source

字符串

必需

源集群的名称。

destination

字符串

必需

目标集群的名称。

buildIndexes

字符串

Optional

在同步期间配置索引构建。

支持的选项：

afterDataCopy （运行MongoDB 6.0 或更高版本的源集群中的默认）导致 mongosync 在集合复制后在目标集群上构建索引。这包括源集群在初始化点存在的索引以及迁移过程中创建的索引。这样可以加快索引数据库的迁移速度。

If the value of buildIndexes is "afterDataCopy" or "excludeHashedAfterCopy" and you set createSupportingIndexes to false while migrating to a sharded cluster, mongosync creates a dummy index to support the shard key. mongosync attempts to drop this dummy index after commit is called. If no user-built indexes exist to support the shard key, dropping the dummy index will fail. Users are advised to drop the dummy index and create their own index after migration completes.

重要提示：仅运行MongoDB 6.0 或更高版本的源集群支持此参数。
beforeDataCopy （运行6.0 之前版本的源集群中的默认）导致 mongosync 在初始化期间在目标集群上构建索引。这包括源集群在初始化点存在的索引以及迁移过程中创建的索引。
excludeHashed causes mongosync to skip building hashed indexes during sync. This can improve performance for large collections.
excludeHashedAfterCopy 导致 mongosync 在集合复制后在目标集群上构建非哈希索引。excludeHashedAfterCopy 还会跳过构建哈希索引的过程。由于在初始数据复制后构建索引并跳过构建哈希索引，因此这可以加快索引数据库的迁移速度。

If the value of buildIndexes is "afterDataCopy" or "excludeHashedAfterCopy" and you set createSupportingIndexes to false while migrating to a sharded cluster, mongosync creates a dummy index to support the shard key. mongosync attempts to drop this dummy index after commit is called. If no user-built indexes exist to support the shard key, dropping the dummy index will fail. Users are advised to drop the dummy index and create their own index after migration completes.

重要提示：仅运行MongoDB 6.0 或更高版本的源集群支持此参数。
never 导致mongosync在同步期间跳过构建不必要的索引。这可以提高迁移性能，尤其是在索引繁重的工作负载下。

如果在启用验证并将 buildIndexes设立为 never 的情况下开始同步，则当 mongosync 在源集群上找到TTL集合时，迁移将失败。这种情况可能发生在您调用 /start 端点之后或更晚的时间，例如，用户在迁移过程中在源集群上创建了TTL索引。

To sync TTL collections without building indexes on the destination cluster, you must start sync with the verifier disabled.

警告：当 mongosync 执行迁移时，请勿在目标集群上手动构建索引。等待迁移完全提交。

For more information on the indexes it does build, see Required Indexes.

/start 当buildIndexes设置为never且reversible设置为true时，会返回错误。

如果调用/start而不指定buildIndexes选项， mongosync将在目标集群上构建索引。

1.3.0版本新增。

detectRandomId

布尔

Optional

When true, mongosync checks for random _id values in collections that are not clustered or capped, and are larger than 20 GiB. If mongosync determines that the collection uses random _id values, it copies the collection in natural order instead of the default _id order. This reduces the time mongosync takes to complete the collection copy phase.

To explicitly specify collections that mongosync copies in natural order, see the copyInNaturalOrder option.

默认情况下，detectRandomId 为 true。

警告：对于 mongosync 选择进行自然扫描的集合，如果迁移中断，则必须在 mongosync 重新启动或恢复时完全重做这些复制操作。这可能会增加 mongosync 完成集合复制阶段所需的时间。

includeNamespaces

阵列

Optional

筛选要同步包含的数据库或collection。

如果在具有多个数据库的源集群上配置筛选器，则mongosync仅同步筛选器定义中指定的数据库。 mongosync不会同步其他现有数据库。

如果要修改筛选器以添加新创建的数据库，则必须从头开始重新启动筛选的同步。

有关更多详细信息，请参阅筛选的同步。

有关当前限制，请参阅Filtered Sync。

1.1版本新增。

excludeNamespaces

阵列

Optional

筛选要从同步中排除的数据库或collection。

如果在具有多个数据库的源集群上配置筛选器，则mongosync仅同步筛选器定义中指定的数据库。 mongosync不会同步其他现有数据库。

如果要修改筛选器以添加新创建的数据库，则必须从头开始重新启动筛选的同步。

有关更多详细信息，请参阅筛选的同步。

有关当前限制，请参阅Filtered Sync。

1.6版本新增。

copyInNaturalOrder

文档数组

Optional

Copies a list of databases and collections in their natural order to the destination cluster. The natural order is the order in which you previously inserted the documents into the database. You must pass in an array of documents that each represent a database and its collections. For a syntax example, see Natural Scan Capability.

IMPORTANT: Only use the copyInNaturalOrder option for collections that explicitly set a random _id field and are larger than 30 GiB. Using this option for collections of size 30 GiB or greater significantly reduces the time that the collection copy phase takes.

警告：如果在为大小大于 500 GB 的集合启用 copyInNaturalOrder 选项的 /pause 或中断之后 /resume mongosync迁移，则迁移可能需要多个小时才能完成。

The detectRandomId option uses a lower collection size threshold of 20 GiB because it rigorously checks that collections have a low degree of correlation between the _id vales and their insertion order. copyInNaturalOrder has a higher threshold of 30 GiB because users might be more relaxed in their selection of collections to copy in natural order.

preExistingDestinationData

布尔

Optional

重要提示：此功能目前处于公开预览阶段。请查看本节中的行为和限制，以便在生产环境中使用此功能。

默认值为false 。

如果设立为true ：

mongosync 允许目标集群上预先存在的命名空间。
您必须在请求中使用 includeNamespaces 和 excludeNamespaces 参数之一或两者来指定命名空间过滤。
目标集群不得包含与迁移的命名空间冲突的命名空间。
如果启用了嵌入式验证，则命名空间过滤必须过滤出目标集群上任何预先存在的集合或索引，即使它们在源集群上不存在。否则，嵌入式验证将失败。
确保遵循转换进程中的所有指示，以确保源集群或目标集群上不会发生不安全写入。启用此功能时，mongosync 不会启用写入阻塞，因此您必须手动确保不会发生这些写入。
mongosync 不能确保目标集群上存在足够的资源（例如磁盘空间、计算和oplog ）来容纳迁移的额外负载。监控目标集群，确保其拥有足够的资源。
mongosync 使用此功能时不会迁移视图。它会在迁移期间忽略源集群上的视图。您必须在切换后单独迁移视图。
默认负载级别从 3 更改为 2。
您可以在迁移期间为分片的目标集群启用负载负载均衡器。
mongosync 不会区块对源集群或目标集群的写入。要学习；了解更多信息，请参阅写入阻塞。
mongosync 不允许反向迁移。

mongosync 在迁移开始时输出以下日志消息：

ATTENTION! Data migration to a non-empty cluster is allowed
with the preExistingDestinationData set to true in the
request to start migration. This feature is currently in
preview. Please see https://www.mongodb.com/zh-cn/docs/cluster-to-cluster-sync/current/reference/api/start/
for important requirements and limitations.

请参阅筛选的同步限制。

reversible

布尔

Optional

如果设置为true ，则启用反向同步操作。

以下配置不支持此选项：

从副本集同步到分片集群
同步具有不同分片数量的分片集群
当buildIndexes设置为never时可逆同步。

重要提示：仅运行MongoDB 6.0 或更高版本的源集群支持将可逆设置为 true。

有关更多信息，请参阅反向端点。

默认值为false 。

sharding

文档

Optional

配置副本集和分片集群之间的同步。从副本集同步到分片集群需要此选项。

For more information, see Sharding Parameters.

1.1版本新增。

verification

文档

Optional

配置嵌入式验证器。

For more information, see Embedded Verifier.

1.9版本新增。

verification.enabled

bool

Optional

启用嵌入式验证程序。验证程序对目标集群上支持的集合执行一系列验证检查，以确认迁移成功。

如果验证者没有发现错误，mongosync 将转换到 COMMITTED 状态。如果确实遇到错误，迁移将失败。

默认下启用验证程序。

警告：验证程序不会检查所有集合或数据。有关详细信息，请参阅嵌入式验证器。

1.9版本新增。

分片参数

1.1版本新增。

要将副本集同步到分片集群，请将sharding选项设置为目标集群上的collection。

mongosync 从副本集同步到分片集群时，如果未设置sharding选项，则会引发错误。如果将sharding选项与任何其他配置一起设置， mongosync也会引发错误。

sharding选项具有以下参数：

Parameter	类型	说明
`createSupportingIndexes`	布尔	可选。设置同步是否为分片键创建支持索引（如果不存在）。默认值为 `false`。 If the value of `buildIndexes` is `"afterDataCopy"` or `"excludeHashedAfterCopy"` and you set createSupportingIndexes to `false` while migrating to a sharded cluster, `mongosync` creates a dummy index to support the shard key. `mongosync` attempts to drop this dummy index after `commit` is called. If no user-built indexes exist to support the shard key, dropping the dummy index will fail. Users are advised to drop the dummy index and create their own index after migration completes. 如果将此参数设立为 `true` 并将 `buildIndexes`设立为 `"excludeHashed"` 或 `"excludeHashedAfterCopy"`，则 `mongosync` 不会在目标集群上为哈希分片键创建支持哈希分片。`mongosync` 仍会为非哈希分片片键构建非哈希支持索引。 For more information and limitations, see Supporting Indexes.
`shardingEntries`	文档数组	必需。在同步期间将collection的命名空间和键设置为分片。未包含在此数组中的collection会同步到目标集群上的未分片collection。如果设置为空数组，则不会对任何collection进行分片。
`shardingEntries` `.collection`	字符串	将collection设置为分片。
`shardingEntries` `.database`	字符串	将collection的数据库设置为分片。
`shardingEntries` `.shardCollection`	文档	设置要在目标集群上生成的分片键。
`shardingEntries` `.shardCollection` `.key`	阵列	设置用于分片键的字段。有关更多信息，请参阅分片键。

响应

字段	类型	说明
`success`	布尔	当请求成功时，该值为`true` 。
`error`	字符串	如果发生错误，则指示错误名称。当`success`为`true`时，响应中将省略此字段。
`errorDescription`	字符串	所发生错误的详细描述。当`success`为`true`时，响应中将省略此字段。

示例

启动同步作业

以下示例在源集群cluster0 和目标集群cluster1 之间启动同步作业。

请求：

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1"
   } '

响应：

{"success":true}

启动可逆同步作业

以下示例在源集群cluster0 和目标集群cluster1 之间启动同步作业。

reversible字段允许反向同步。要反转同步方向，请参阅：反向。

请求：

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "reversible": true
   } '

响应：

{"success":true}

启动筛选的同步作业

以下示例在源集群cluster0 和目标集群cluster1 之间启动同步作业。

cluster0 包含sales 、 marketing和engineering数据库。

sales 数据库包含 EMEA、APAC 和 AMER 集合。

此示例中的 includeNamespaces 数组定义了两个数据库 sales 和 marketing 上的筛选器。

sales 数据库还会对 EMEA 和 APAC 集合进行过滤。

"includeNamespaces" : [
      {
          "database" : "sales",
          "collections": [ "EMEA", "APAC" ]
      },
      {
          "database" : "marketing"
      }
   ]

使用此过滤器调用 /start API 后，mongosync：

同步 marketing 数据库中的所有集合
滤除 engineering 数据库
同步 sales 数据库中的 EMEA 和 APAC 集合
滤除 AMER 集合

includeNamespaces选项会创建一个筛选器。要筛选同步，请参阅：筛选的同步

请求：

curl -X POST "http://localhost:27182/api/v1/start" --data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "includeNamespaces": [
         {
             "database": "sales",
             "collectionsRegex": {
                "pattern": "^accounts_.+$",
                "options": "i"
             }
         }, {
            "database": "marketing"
         }
      ]
   } '

响应：

{"success":true}

开始从副本集同步到分片集群

以下示例在源副本集cluster0 和目标分片集群cluster1 之间启动同步作业。此示例中的 key大量定义了分片键{"location": 1, "region": 1 }。

请求：

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "sharding": {
         "createSupportingIndexes": true,
         "shardingEntries": [
            {
                "database": "accounts",
                "collection": "us_east",
                "shardCollection": {
                   "key": [
                      { "location": 1 },
                      { "region": 1 }
                   ]
                }
            }
         ]
      }
   } '

响应：

{"success":true}

从禁用验证器的情况下启动

从 1.9 开始，开始迁移时默认运行嵌入式验证程序。如需禁用，请将 verification.enabled设立为 false。

请求：

curl localhost:27182/api/v1/start -XPOST \
--data '
   {
      "source": "cluster0",
      "destination": "cluster1",
      "verification": {
         "enabled": false
      }
   } '

响应：

{"success":true}

在将应用程序负载转移到目标集群之前，应验证迁移是否成功。如果出于任何原因需要禁用验证程序，请使用替代方法来验证同步。

行为

嵌入式验证程序

从 1.9 开始，mongosync 提供嵌入式验证器，以确定从源集群到目标的数据传输是否成功。

启用后，验证程序将对目标集群执行一系列验证检查。如果其中任何检查返回错误，则验证程序迁移失败。如果所有检查均成功，mongosync 将转换为 COMMITTED 状态。

要禁用验证程序，请参阅在禁用验证程序的情况下启动。

如果您启用源集群或目标集群不支持的验证检查，或者内存不足，则 /start 端点会返回错误。

州

如果start请求成功， mongosync将进入RUNNING状态。

分片副本集

从副本集同步到分片集群需要sharding选项。此选项配置mongosync如何对collection进行分片。

sharding.shardingEntries数组指定要分片的collection。未在此数组中列出的collection将复制为未分片。

有关更多信息，请参阅分片集群行为。

支持索引

mongosync 将索引从源集群同步到目标集群。从副本集同步到分片集群时，mongosync 可能需要额外的索引来支持分片键，而源集群上可能不存在该索引。

mongosync 可以在同步期间为分片collection创建支持索引。这是通过设置sharding.createSupportingIndexes选项来完成的。

当sharding.createSupportingIndexes为false （默认值）时：

您为sharding.shardingEntries选项提供的每个分片键都必须在源集群上具有现有索引。
如果集合使用任何其他排序规则，则用于分片键的索引之一必须具有简单排序规则。
要在分片键中使用唯一索引，您必须在源集群上创建索引时指定其唯一性。
源集群上的唯一索引与目标集群上请求的分片键不兼容，例如源集群上的唯一索引不包含目标集群上请求的分片键作为前缀，可能会导致mongosync失败。
If the value of buildIndexes is "afterDataCopy" or "excludeHashedAfterCopy" and you set createSupportingIndexes to false while migrating to a sharded cluster, mongosync creates a dummy index to support the shard key. mongosync attempts to drop this dummy index after commit is called. If no user-built indexes exist to support the shard key, dropping the dummy index will fail. Users are advised to drop the dummy index and create their own index after migration completes.

当sharding.createSupportingIndexes为true时：

如果源集群上存在支持索引， mongosync会将索引同步到目标集群并将其用作分片键。
如果支持索引不存在， mongosync则会在目标集群上创建这些索引。

sharding.createSupportingIndexes选项会影响所有分片collection。

在同步期间重命名

sharding.shardingEntries数组中列出的集合在从副本集同步到分片集群时将成为目标集群上的分片集合。

Renaming a collection (such as with the renameCollection command) on the source cluster after calling start but before mongosync begins to copy the collection can block the collection from sharding on the destination.

注意

从副本集同步到分片集群时，不支持重命名collection以使用不同的数据库。

要检查重命名collection是否安全，请调用progress端点并检查返回文档中collectionCopy.estimatedCopiedBytes字段的值。

值为 0 表示mongosync尚未开始复制collection。

在此点重命名collection可能会导致目标集群上出现未分片的collection，因为可能会在重命名对源生效之前过渡到复制。
值大于 0 表示mongosync已开始复制。从此时开始重命名collection不会阻止其在目标集群上的分片，即使发生事件也是如此。

所需索引

当您在buildIndexes选项设置为never的情况下调用/start时， mongosync会跳过构建不必要的索引。

始终构建的索引包括：

mongosync 为其复制的每个collection的_id字段构建索引。
mongosync 为每个没有索引的分分片的集合构建虚拟索引，以支持目标集群上的分分片键。当buildIndexes设立为never时， mongosync在提交后保留此索引。

端点保护

mongosync 不保护start端点。但是，默认情况下，该 API 仅绑定到本地主机，不接受来自其他来源的调用。此外， start调用不会公开连接档案或用户数据。

自然扫描功能

当使用 copyInNaturalOrder 选项调用 /start 时，必须使用文档指定数据库和集合，如以下示例所示。

请求：

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": "sales",
        "collections": [
          "accounts",
          "orders",
        ]
      },
      {
        "database": "marketing",
        "collections": [
          "offers",
        ]
      },
    ]
  }'

响应：

{"success":true}

警告：如果您为具有非随机 _id 字段的集合启用迁移，则当您指定 copyInNaturalOrder 时，集合复制阶段可能需要更长的时间才能完成。

您可以使用 copyInNaturalOrder 按自然顺序复制多个数据库中的所有集合，如下示例所示。

请求：

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": "sales",
      },
      {
        "database": "marketing",
      },
    ]
  }'

响应：

{"success":true}

您可以使用 copyInNaturalOrder 按自然顺序复制所有数据库及其集合。

请求：

curl -X POST "http://localhost:27182/api/v1/start" --data '
  {
    "source": "cluster0",
    "destination": "cluster1",
    "copyInNaturalOrder": [
      {
        "database": ".",
      },
    ]
  }'

响应：

{"success":true}

start

说明

要求

州

权限

多个 mongosync 实例

请求

请求正文参数

分片参数

响应

示例

启动同步作业

启动可逆同步作业

启动筛选的同步作业

开始从副本集同步到分片集群

从禁用验证器的情况下启动

行为

嵌入式验证程序

州

分片副本集

支持索引

在同步期间重命名

所需索引

端点保护

自然扫描功能

`start`

多个 `mongosync` 实例