/ /

`start`

説明

ソースクラスターと宛先クラスター間の同期を開始します。

要件

状態

startエンドポイントを使用するには、 mongosyncがIDLE状態である必要があります。

権限

mongosync 接続stringで指定されたユーザーには、ソースクラスターと宛先クラスターで必要な権限が必要です。「ユーザー権限」を参照して、ユーザーが同期を開始するための適切な権限を持っていることを確認します。

複数の `mongosync` インスタンス

mongosyncを起動するときに、 cluster0またはcluster1設定の接続文字列で構成済みのmongosyncユーザーを使用していることを確認します。

注意

シャーディングされたクラスター間で同期するように複数のmongosyncインスタンスを構成する場合は、各mongosyncインスタンスに同一の API エンドポイントコマンドを送信する必要があります。

詳しくは、「複数の Mongosync を開始する」を参照してください。

リクエスト

POST /api/v1/start

リクエストボディパラメータ

Parameter

タイプ

必要性

説明

source

string

必須

ソースクラスターの名前。

destination

string

必須

宛先クラスターの名前。

buildIndexes

string

任意

同期中のインデックスビルドを構成します。

サポートされているオプション:

afterDataCopy （ MongoDB 6.0 以降を実行中ソースクラスターのデフォルト）、コレクションのコピー後に mongosync は宛先クラスターにインデックスを構築します。これには、初期化の点でソースクラスターに存在するインデックスと、移行中に作成されたインデックスが含まれます。これにより、インデックスデータベースの移行が高速化されます。

の値がbuildIndexes "afterDataCopy"または"excludeHashedAfterCopy" falseで、シャーディングされたクラスターへの移行中に createSupportIndexes をに設定すると、mongosync はシャードキーをサポートするためのダミーのインデックスを作成します。mongosync commitが呼び出された後に、はこのダミーインデックスを削除しようとします。シャードキーをサポートするユーザーが構築したインデックスが存在しない場合、ダミーインデックスの削除は失敗します。ユーザーは、移行が完了した後にダミーインデックスを削除し、独自のインデックスを作成することをお勧めします。

重要: このパラメーターはMongoDB6.0 以降を実行中ソースクラスターでのみサポートされています。
beforeDataCopy （6.0 より前を実行中ソースクラスターのデフォルト）により、初期化中に mongosync が宛先クラスターにインデックスを構築します。これには、初期化の点でソースクラスターに存在するインデックスと、移行中に作成されたインデックスが含まれます。
excludeHashed mongosyncでは、同期中にがハッシュインデックスのビルドをスキップします。これにより、大規模なコレクションのパフォーマンスが向上します。
excludeHashedAfterCopy により、コレクションコピー後に mongosync は宛先クラスターに非ハッシュインデックスを構築します。excludeHashedAfterCopy はハッシュインデックスの構築もスキップします。これにより、初期データコピー後にインデックスが構築され、ハッシュされたインデックスの構築がスキップされるため、インデックス付きデータベースの移行が高速化されます。

の値がbuildIndexes "afterDataCopy"または"excludeHashedAfterCopy" falseで、シャーディングされたクラスターへの移行中に createSupportIndexes をに設定すると、mongosync はシャードキーをサポートするためのダミーのインデックスを作成します。mongosync commitが呼び出された後に、はこのダミーインデックスを削除しようとします。シャードキーをサポートするユーザーが構築したインデックスが存在しない場合、ダミーインデックスの削除は失敗します。ユーザーは、移行が完了した後にダミーインデックスを削除し、独自のインデックスを作成することをお勧めします。

重要: このパラメーターはMongoDB6.0 以降を実行中ソースクラスターでのみサポートされています。
never により、同期中にmongosyncは不要なインデックスのビルドをスキップするようになります。これにより、特にインデックス負荷の高いワークロードにおいて、移行のパフォーマンスが向上します。

検証を有効にして同期を開始し、buildIndexes を never に設定している場合、mongosync がソースクラスターで TTLコレクションを見つけると、移行は失敗します。これは、/start エンドポイントを呼び出した後に発生する可能性があり、移行の進行中にユーザーがソースクラスターに TTLインデックスを作成する場合などです。

宛先クラスターでインデックスを構築せずに TTL コレクションを同期するには、検証子を無効にして同期を開始する必要があります。

警告: mongosync が移行を実行している間は、宛先クラスターにインデックスを手動でビルドしないでください。移行が完全にコミットされるまで待ちます。

ビルドが構築するインデックスの詳細については、「必要なインデックス」を参照してください。

/start は、 buildIndexesがneverに設定され、かつreversibleがtrueに設定されている場合にエラーを返します。

buildIndexesオプションを指定せずに/startを呼び出すと、 mongosyncは宛先クラスターにインデックスを構築します。

バージョン1.3.0の新機能。

detectRandomId

ブール値

任意

true の場合、mongosync は、クラスタ化または上限付きではなく、20 GiB より大きいコレクション内のランダムな _id 値をチェックします。 mongosync がコレクションがランダムな _id 値を使用していると判断した場合、コレクションはデフォルトの_id 順序ではなく、自然な順序でコレクションがコピーされます。これにより、mongosync がコレクションコピーフェーズを完了するのにかかる時間が短縮されます。

mongosyncが自然な順序でコピーするコレクションを明示的に指定するには、 copyIn Natural Order オプションを参照してください。

デフォルトでは、 detectRandomId は true です。

警告: mongosync が自然なスキャンに選択するコレクションでは、移行が中断された場合、mongosync の再起動または再開時にこれらのコピー操作を完全に書き換える必要があります。これにより、mongosync がコレクションコピーフェーズを完了するのにかかる時間が長くなる可能性があります。

includeNamespaces

配列

任意

同期に含めるデータベースまたはコレクションをフィルタリングします。

複数のデータベースを持つソースクラスターでフィルターを構成する場合、 mongosyncはフィルター定義で指定されたデータベースのみを同期します。 mongosyncは既存の他のデータベースを同期しません。

フィルターを変更して新しいデータベースを追加する場合は、フィルタリングされた同期を最初から再開する必要があります。

詳しくは、「フィルタリングされた同期」を参照してください。

現在の制限については、「フィルタリングされた同期」を参照してください。

バージョン1.1の新機能。

excludeNamespaces

配列

任意

同期から除外するデータベースまたはコレクションをフィルタリングします。

フィルターを変更して新しいデータベースを追加する場合は、フィルタリングされた同期を最初から再開する必要があります。

詳しくは、「フィルタリングされた同期」を参照してください。

現在の制限については、「フィルタリングされた同期」を参照してください。

バージョン1.6の新機能。

copyInNaturalOrder

ドキュメントの配列

任意

データベースとコレクションのリストを自然な順序で宛先クラスターにコピーします。自然な順序とは、過去にデータベースにドキュメントを挿入した順序です。それぞれがデータベースとそのコレクションを表すドキュメントの配列を渡す必要があります。構文の例については、「 Natural Scan 機能」を参照してください。

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移行を実行する場合、移行が完了するまでに複数時間かかることがあります。

trigger オプションは、コレクションが20 _idの値と挿入順序の間に相関が低いことを厳密にチェックするため、 GiB というより低いコレクションサイズのしきい値を使用します。copyInNaturalOrder 30では、ユーザーは自然な順序でコピーするコレクションの選択がより緩和される可能性があるため、しきい値は GiB より高くなります。

preExistingDestinationData

ブール値

任意

重要: この機能は現在、パブリックプレビュー段階です。この機能を本番環境で使用するには、このセクションの「動作と制限」を確認してください。

デフォルト値はfalseです。

trueに設定されている場合:

mongosync は、宛先クラスター上で既存の名前空間を許可します。
リクエストで includeNamespaces パラメータと excludeNamespaces パラメータの 1 つまたは両方を使用して名前空間フィルタを指定する必要があります。
宛先クラスターには、移行した名前空間と競合する名前空間を含めることはできません。
埋め込み検証が有効になっている場合、名前空間フィルターは、ソースクラスターに存在しない場合でも、宛先クラスターに既存のコレクションまたはインデックスを除外する必要があります。合格していない場合は、埋め込み検証に失敗します。
ソースクラスターまたは宛先クラスターで安全でない書込み (write) が発生しないよう、カットオーバーのすべての方向に実行していることを確認してください。この機能を有効にしても、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/ja-jp/docs/cluster-to-cluster-sync/current/reference/api/start/
for important requirements and limitations.

「フィルタリングされた同期の制限」を参照してください。

reversible

ブール値

任意

trueに設定すると、同期操作を元に戻すことができます。

このオプションは、次の構成ではサポートされていません。

レプリカセットからシャーディングされたクラスターへの同期
シャードの数が異なるシャーディングされたクラスターの同期
buildIndexesがneverに設定されている場合は、元に戻すことができます。

重要: true への可用な設定は、 MongoDB 6.0 以降を実行中ソースクラスターでのみサポートされています。

詳細については、「逆のエンドポイント」を参照してください。

デフォルト値はfalseです。

sharding

ドキュメント

任意

レプリカセットとシャーディングされたクラスターとの間の同期を構成します。レプリカセットからシャーディングされたクラスターへの同期にはこのオプションが必要です。

詳細については、「シャーディングパラメータ」を参照してください。

バージョン1.1の新機能。

verification

ドキュメント

任意

埋め込み検証子を構成します。

詳細については、「埋め込み検証子」を参照してください。

バージョン1.9の新機能。

verification.enabled

ブール

任意

埋め込み検証子を有効にします。検証ツールは、宛先クラスターでサポートされているコレクションに対して一連の検証チェックを実行し、移行が成功したことを確認します。

検証子でエラーが検出されない場合、mongosync は COMMITTED 状態に移行します。エラーが発生した場合、移行は失敗します。

検証子はデフォルトで有効になっています。

警告 : 検証子は、すべてのコレクションまたはデータをチェックするわけではありません。詳細については、「埋め込み検証子」を参照してください。

バージョン1.9の新機能。

シャーディングパラメータ

バージョン1.1の新機能。

レプリカセットからシャーディングされたクラスターに同期するには、 shardingオプションを設定して、宛先クラスターのコレクションをシャードします。

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` は、ハッシュされていないシャードキー用のハッシュされていないサポートインデックスを引き続き構築します。詳細と制限については、「インデックスのサポート」を参照してください。
`shardingEntries`	ドキュメントの配列	必須。同期中にシャードするコレクションの名前空間とキーを設定します。この配列に含まれていないコレクションは、宛先クラスター上のシャーディングされていないコレクションに同期されます。空の配列に設定されている場合、コレクションはシャーディングされません。
`shardingEntries` `.collection`	string	コレクションをシャードに設定します。
`shardingEntries` `.database`	string	コレクションのデータベースをシャードに設定します。
`shardingEntries` `.shardCollection`	ドキュメント	宛先クラスターで生成するシャードキーを設定します。
`shardingEntries` `.shardCollection` `.key`	配列	シャードキーに使用するフィールドを設定します。詳しくは、シャードキーを参照してください。

応答

フィールド	タイプ	説明
`success`	ブール値	リクエストが成功した場合、この値は`true`になります。
`error`	string	エラーが発生した場合、はエラーの名前を示します。このフィールドは、 `success`が`true`の場合、応答から省略されます。
`errorDescription`	string	発生したエラーの詳細な説明。このフィールドは、 `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の 2 つのデータベースに対するフィルターを定義しています。

salesEMEAデータベースは、APAC コレクションとコレクションでもフィルタリングします。

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

/startこのフィルターを使用して API を呼び出すと、mongosync は次のようになります。

marketingデータベース内のすべてのコレクションを同期します
engineeringデータベースをフィルタリング除外します
EMEAAPACデータベースからsales コレクションとコレクションを同期します
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がコレクションをシャーディングする方法を構成します。

sharding.shardingEntries配列は、シャーディングするコレクションを指定します。この配列にリストされていないコレクションは、シャーディングされていないコレクションとして複製されます。

詳しくは、「シャードクラスタの動作」を参照してください。

サポートインデックス

mongosync は、ソースクラスターから宛先クラスターにインデックスを同期します。レプリカセットからシャーディングされたクラスターに同期する場合、mongosync はシャードキーをサポートするために追加のインデックスが必要になる場合があります。このインデックスはソースクラスターに存在しない場合があります。

mongosync は、同期中にシャーディングされたコレクション用のサポートインデックスを作成できます。そのためには、 sharding.createSupportingIndexesオプションを設定します。

sharding.createSupportingIndexesがfalse （デフォルト）の場合

sharding.shardingEntriesオプションに指定する各シャードキーには、ソースクラスターに既存のインデックスが必要です。
コレクションで他の照合を使用する場合、シャードキーに使用されるインデックスの 1 つは単純照合が必要です。
シャードキーで一意のインデックスを使用するには、ソースクラスターでインデックスを作成するときに、その一意性を指定する必要があります。
宛先クラスターのリクエストされたシャードキーと互換性のないソースクラスターのユニークインデックス（宛先のプレフィックスとして、リクエストされたシャードキーを含まないソースクラスターのユニークインデックスなど）では、 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オプションは、すべてのシャーディングされたコレクションに影響します。

同期中の名前変更

レプリカセットからシャーディングされたクラスターに同期されたときにsharding.shardingEntries配列にリストされているコレクションは、宛先クラスターでシャーディングされたコレクションになります。

renameCollectionを呼び出した後、がコレクションのコピーを開始する前に、ソースクラスターでコレクションを変更すると（start mongosyncコマンドなど）、宛先でのコレクションのシャーディングがブロックされる可能性があります。

注意

レプリカセットからシャーディングされたクラスターへの同期中に別のデータベースを使用するようにコレクションの名前を変更することはサポートされていません。

コレクションの名前を変更しても安全かどうかを確認するには、 progressエンドポイントを呼び出し、返されたドキュメントのcollectionCopy.estimatedCopiedBytesフィールドの値を確認します。

値が 0 の場合、 mongosyncによるコレクションのコピーが開始されていないことを示します。

この時点でコレクションの名前を変更すると、ソースで名前変更が有効になる前にコピーへの移行が行われる可能性があるため、宛先クラスターでシャーディングされないコレクションが作成される可能性があります。
値が 0 より大きい場合は、 mongosyncがコピーを開始したことを示します。この時点からコレクションの名前を変更しても、クラッシュが発生した場合でも、宛先クラスターでのシャーディングはブロックされません。

必要なインデックス

buildIndexesオプションをneverに設定して/startを呼び出すと、 mongosyncは不要なインデックスの構築をスキップします。

常に構築されるインデックスには、次のものが含まれます。

mongosync は、コピーしたすべてのコレクションの_idフィールドにインデックスを構築します。
mongosync は、宛先クラスターでシャードキーをサポートするためのインデックスがない各シャーディングされたコレクションに対してダミーのインデックスを構築します。 buildIndexesがneverに設定されている場合、 mongosyncはコミット後にこのインデックスを保持します。

エンドポイント保護

mongosync は、 startエンドポイントを保護しません。ただし、デフォルトでは、API は localhost のみにバインドされ、他のソースからの呼び出しは受け入れません。さらに、 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` インスタンス

リクエストボディパラメータ

シャーディングパラメータ

検証子を無効にしてを開始する