Docs Menu
Docs Home
/
MongoDB Cluster-to-Cluster Sync
/
参照
/
mongosync API エンドポイント

start

説明

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

要件

状態

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

権限

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

複数のmongosync インスタンス

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

注意

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

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

リクエスト

POST /api/v1/start

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

Parameter
タイプ
必要性
説明

source

string

必須

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

destination

string

必須

宛先クラスターの名前。

buildIndexes

string

任意

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

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

  • beforeDataCopy （デフォルトの）により、mongosync は宛先クラスターにインデックスを構築します。これらには、既存のインデックス、ハッシュされたインデックス、およびソースクラスターで移行中に作成されたインデックスが含まれます。

  • excludeHashed mongosyncでは、同期中に がハッシュ インデックスのビルドをスキップします。これにより、大規模なコレクションのパフォーマンスが向上します。

  • never により、同期中にmongosyncは不要なインデックスのビルドをスキップするようになります。 これにより、特にインデックス負荷の高いワークロードにおいて、移行のパフォーマンスが向上します。

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

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

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

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

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

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

バージョン 1.3.0 の新機能。

enableUserWriteBlocking

string またはブール値

任意

重要: 6.0 より前のバージョンから移行している場合ソースクラスターでは、このパラメーターは設定できません。

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

  • "sourceAndDestination":移行の進行中に宛先クラスターへの書込みをブロックし、/progress エンドポイントが canWrite が true であることを報告する直前に書込みのブロックを解除します。mongosync が /commit エンドポイントを呼び出した後、ソースクラスターへの書込みをブロックします。

    下位互換性のために true を使用することもできます。

  • "none": 書込みブロックは発生しません。下位互換性のために false を使用することもできます。

  • "destinationOnly":移行の進行中に宛先クラスターへの書込みをブロックし、canWrite が true になる直前に書込みのブロックを解除します。

逆同期するには、 enableUserWriteBlockingフィールドを"sourceAndDestination"に設定する必要があります。 移行テストを実行した後など、ソースクラスターが再度書込み (write) を受け入れられるようにするには、次のコマンドを実行します。

db.adminCommand( { setUserWriteBlockMode: 1, global: false } )

デフォルト値は"destinationOnly"です。

includeNamespaces

配列

任意

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

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

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

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

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

バージョン 1.1 の新機能。

excludeNamespaces

配列

任意

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

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

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

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

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

バージョン 1.6 の新機能.

preExistingDestinationData

ブール値

任意

重要

This feature is currently in Public Preview. Please review the behavior and limitations in this section in order to use this feature in production environments.

デフォルト値はfalseです。

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

  • mongosync は、宛先クラスター上で既存の名前空間を許可します。

  • リクエストで includeNamespaces パラメータと excludeNamespaces パラメータの 1 つまたは両方を使用して名前空間フィルタを指定する必要があります。

  • 埋め込み検証が有効になっている場合、名前空間フィルターは、ソースクラスターに存在しない場合でも、宛先クラスターに既存のコレクションまたはインデックスを除外する必要があります。合格していない場合は、埋め込み検証に失敗します。

  • ソースクラスターまたは宛先クラスターで安全でない書込みmongosync (write) が発生しないよう、カットオーバーのすべての方向に実行していることを確認してください。この機能を有効にしても、 では書込みブロックが有効にならないため、これらの書込みが発生しないように手動で確認する必要があります。

  • mongosync は、ディスク容量、コンピュート、 oplogなどの十分なリソースが宛先クラスターに存在し、移行の追加負荷に対応するために十分なリソースが存在することを保証するものではありません。宛先クラスターをモニターして、十分なリソースがあることを確認します。

  • mongosync この機能を使用する場合、 は ビューを移行しません 。移行中はソースクラスター上のビューは無視されます。カットオーバー後にビューを個別に移行する必要があります。

  • デフォルトの負荷レベルが 3から2 に変更されました。

  • 移行中に、シャーディングされた宛先クラスターのバランサーを有効のままにすることができます。

  • デフォルトの書込みブロックモードが "destinationOnly"から"none" に変更されました。書込みブロックはクラスター レベルでのみ使用できるため、ソースクラスターまたは宛先クラスターの個々のコレクションに対して書込みブロックを設定することはできません。また、名前空間フィルタリングは二重書込みブロックと互換性がありません。

  • 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に設定すると、同期操作を元に戻すことができます。

逆同期するには、 enableUserWriteBlockingフィールドをsourceAndDestinationに設定する必要があります。

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

  • レプリカセットからシャーディングされたクラスターへの同期

  • シャードの数が異なるシャーディングされたクラスターの同期

  • buildIndexesがneverに設定されている場合は、元に戻すことができます。

重要: より前のバージョンから移行している場合6.0ソースクラスター、reversible を true に設定することはできません。

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

デフォルト値はfalseです。

sharding

ドキュメント

任意

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

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

バージョン 1.1 の新機能。

verification

ドキュメント

任意

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

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

バージョン 1.9 の新機能。

verification.enabled

ブール

任意

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

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

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

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

バージョン 1.9 の新機能。

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

バージョン 1.1 の新機能。

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

mongosync レプリカセットからシャーディングされたクラスターに同期するときにshardingオプションが設定されていない場合、 はエラーをスローします。 また、 shardingオプションが他の構成で設定されている場合、 mongosyncではエラーがスローされます。

shardingオプションには次のパラメーターがあります。

Parameter
タイプ
説明

createSupportingIndexes

ブール値

任意。 同期がシャードキーのサポートインデックスを作成するかどうかを設定します（存在しない場合）。 デフォルトはfalse です。

このパラメータを true に設定し、buildIndexes を "excludeHashed" に設定すると、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とenableUserWriteBlockingフィールドでは同期を元に戻すことができます。 同期方向を逆にするには、「逆 」を参照してください。

リクエスト:

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

応答:

{"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が失敗する可能性があります。

sharding.createSupportingIndexesがtrueの場合:

  • サポートするインデックスがソースクラスターに存在する場合、 mongosyncはインデックスを宛先クラスターに同期し、シャードキーとして使用します。

  • サポート インデックスが存在しない場合、 mongosyncは宛先クラスターにそれらを作成します。

sharding.createSupportingIndexesオプションは、すべてのシャーディングされたコレクションに影響します。

同期中の名前変更

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

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

注意

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

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

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

    この時点でコレクションの名前を変更すると、ソースで名前変更が有効になる前にコピーへの移行が行われる可能性があるため、宛先クラスターでシャーディングされないコレクションが作成される可能性があります。

  • 値が 0 より大きい場合は、 mongosyncがコピーを開始したことを示します。 この時点からコレクションの名前を変更しても、クラッシュが発生した場合でも、宛先クラスターでのシャーディングはブロックされません。

必要なインデックス

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

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

  • mongosync は、コピーしたすべてのコレクションの_idフィールドにインデックスを構築します。

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

エンドポイント保護

mongosync は、 startエンドポイントを保護しません。 ただし、デフォルトでは、API は localhost のみにバインドされ、他のソースからの呼び出しは受け入れません。 さらに、 start呼び出しでは接続認証情報やユーザー データは公開されません。

戻る

mongosync API エンドポイント

次へ

進行状況

項目一覧