Microsoft Learnの「Migrate Data Using the Data Migration Tool – Azure Cosmos DB」でまず押さえるべき結論は、Azure Cosmos DB Data Migration Toolは、Azure Cosmos DBへのデータ取り込み・書き出しを行うオープンソースのコマンドラインツールであり、移行先の選定やデータモデル設計まで自動で解決するツールではないという点です。特に2026年5月15日時点で確認すべき重要ポイントは、MongoDB互換性を重視する移行ではAzure DocumentDB向けの個別ガイダンスを確認し、MongoDBからAzure Cosmos DB for NoSQLへ移す場合はクロスAPI移行として設計を見直す必要があることです。(Microsoft Learn)
この記事では、Azure Cosmos DB Data Migration Toolの変更点、影響を受ける管理者・開発者、migrationsettings.jsonで確認すべき設定、DockerやCI/CDで展開する際の注意点を、実務でそのまま使える判断基準として整理します。
Azure Cosmos DB Data Migration Toolの更新で確認すべきポイント
Azure Cosmos DB Data Migration Toolは、JSON、MongoDB、SQL Server、PostgreSQL、CSV、Parquet、Azure Blob Storage、AWS S3などをソースまたはシンクとして扱える拡張モデルのツールです。公式ドキュメントでは、Azure Cosmos DB for NoSQL、MongoDB、Tableに適用される記事として説明されています。(Microsoft Learn)
今回の確認ポイントは、単なる「使い方の更新」ではありません。移行プロジェクトで誤解しやすい MongoDB互換性の扱い、NoSQL APIへのクロスAPI移行、Docker・コマンドライン実行時の設定管理を見直すことが中心です。
| 確認項目 | 実務上の意味 | すぐ確認すべきこと |
|---|---|---|
| MongoDB互換性の扱い | MongoDB互換のアプリをそのまま動かしたいケースでは、Azure DocumentDB向けの移行判断が必要 | 移行先がAzure Cosmos DB for NoSQLなのか、Azure DocumentDBなのかを再確認する |
| Data Migration Toolの位置付け | データのインポート・エクスポート用CLIであり、アプリ移行全体を自動化するものではない | データモデル、インデックス、パーティションキー、アプリ側クエリを別途レビューする |
| サポート拡張機能 | 多様なソース・シンクに対応するが、設定は拡張機能ごとに異なる | 利用する拡張機能のREADMEとmigrationsettings.jsonを突き合わせる |
| 実行環境 | .NET 8.0以降、またはDockerイメージを使う | 開発・検証・本番で同じ実行方式にする |
| 複数移行ジョブ | Operations配列で複数の転送処理を1回の実行にまとめられる | コンテナーごとにパーティションキーと移行順序を確認する |
何が変わるのか：最大のポイントはMongoDB系移行の整理
公式情報で最も注意すべき点は、MongoDBワイヤプロトコル互換性を必要とする場合の案内が明確になったことです。現在の英語版ドキュメントでは、MongoDB wire-protocol compatibilityが必要な場合はAzure DocumentDBへ移行し、Azure DocumentDBの移行ではAzure DocumentDB専用のガイダンスとツールを使うと説明されています。さらに、MongoDBからAzure Cosmos DBへ移行する場合はクロスAPI移行であり、データモデル、スキーマ、インデックスの変更が必要になるとされています。(Microsoft Learn)
ここで誤解しやすいのは、「Data Migration ToolにMongoDB拡張機能がある」ことと、「MongoDBアプリをそのままAzure Cosmos DB for NoSQLへ移せる」ことは同じではない、という点です。MongoDB拡張機能はデータ転送の選択肢ですが、アプリケーション互換性、クエリ仕様、インデックス設計、パーティション設計まで保証するものではありません。
移行先の判断基準
| 現在の状態 | 適した検討先 | 判断理由 |
|---|---|---|
| MongoDBドライバーやMongoDBツールとの互換性を重視したい | Azure DocumentDB | MongoDB wire protocol互換性を前提に設計されたサービスを検討する |
| MongoDBのデータをAzure Cosmos DB for NoSQLの設計に作り替えたい | Azure Cosmos DB for NoSQL | クロスAPI移行として、JSONドキュメント構造、パーティションキー、クエリを再設計する |
| JSON、CSV、ParquetなどのファイルをCosmos DBへ投入したい | Azure Cosmos DB Data Migration Tool | ファイル形式の拡張機能とCosmos DBシンクを組み合わせやすい |
| SQL ServerやPostgreSQLから一部データを取り込みたい | Data Migration Toolを候補にする | 対応拡張機能はあるが、リレーショナルな構造をそのまま移すのではなく非正規化設計が必要 |
| 古いCosmos DB MongoDB API環境を扱っている | MongoDB-Legacy拡張機能の要否を確認 | documents.azure.comエンドポイントなど古いwire version 2環境では専用拡張機能の確認が必要 |
Azure DocumentDBは、Microsoftの公式説明ではMongoDB互換のフルマネージドなドキュメントデータベースとして位置付けられています。既存のMongoDBアプリケーション互換性を優先するなら、Data Migration Toolだけで判断せず、Azure DocumentDB側の互換性・移行ガイダンスを確認するのが安全です。(Microsoft Learn)
影響を受ける管理者・開発者
今回の情報で影響を受けるのは、単にData Migration Toolを実行する担当者だけではありません。移行先のAPI、認証方式、ネットワーク、パーティション設計、CI/CDの実行方式まで関係します。
| 役割 | 確認すべきこと | 見落としやすい失敗 |
|---|---|---|
| Azure管理者 | Cosmos DBアカウント、ネットワーク、RBAC、スループット、バックアップ | 接続文字列を移行用PCに置いたままにする |
| アプリ開発者 | データモデル、クエリ、id、パーティションキー、インデックス | MongoDBやRDBの構造をそのままNoSQL APIへ移す |
| DevOps担当 | Dockerイメージ、GitHub Actions、設定ファイル、シークレット管理 | latestタグのまま本番移行し、検証時と実行バージョンが変わる |
| セキュリティ担当 | AccountKey利用、RBAC、Always Encrypted、SSL検証、プロキシ | 開発用のDisableSslValidationを本番設定に残す |
| データ管理者 | 件数、重複、欠損、移行後の整合性、ロールバック | 成功ログだけを見て、移行後のクエリ結果を検証しない |
Azure Cosmos DB Data Migration Toolでできること
Azure Cosmos DB Data Migration Toolは、ソースとシンクを拡張機能として組み合わせる仕組みです。たとえばJSONをソース、Azure Cosmos DB for NoSQLをシンクにすることで、JSONファイルをCosmos DBコンテナーへ投入できます。公式ドキュメントでは、Azure Cosmos DB for NoSQL、JSON、MongoDB、SQL Server、PostgreSQL、Azure Blob Storage、Parquet、CSV、AWS S3、Azure AI Search、Azure Cosmos DB for Tableなどの拡張機能が挙げられています。(Microsoft Learn)
主な用途は次のとおりです。
- 検証環境へのサンプルデータ投入
- JSONやCSVからCosmos DBへの初期ロード
- SQL ServerやPostgreSQLなどから一部データを抽出してCosmos DBへ投入
- Cosmos DB間、またはCosmos DBから別形式へのエクスポート
- DockerやGitHub Actionsを使った定型的な移行ジョブの実行
一方で、Data Migration Toolはアプリケーション移行全体を代替するものではありません。特にAzure Cosmos DB for NoSQLでは、データをどのように埋め込むか、どの項目を参照にするか、どの値をパーティションキーにするかが、性能・コスト・拡張性を大きく左右します。Microsoftのデータモデリングガイドでも、非構造・半構造データを扱いやすい一方で、性能、スケーラビリティ、コストを最適化するにはデータモデルを考える必要があると説明されています。(Microsoft Learn)
実行方法はDockerかコマンドラインの2択で考える
公式ドキュメントでは、事前構築済みDockerイメージをMicrosoft Container Registryから取得して実行する方法と、GitHubのReleasesから各OS向けの圧縮ファイルをダウンロードしてdmtコマンドを実行する方法が案内されています。前提条件として、ローカル実行では.NET 8.0以降、Docker利用ではDocker Desktopが挙げられています。(Microsoft Learn)
Dockerでの基本形は次のようになります。
docker pull mcr.microsoft.com/azurecosmosdb/linux/azure-cosmos-dmt:latest
docker run \
-v $(pwd)/config:/config \
-v $(pwd)/data:/data \
mcr.microsoft.com/azurecosmosdb/linux/azure-cosmos-dmt:latest \
run --settings /config/migrationsettings.json検証ではlatestタグでも始めやすいですが、本番移行やCI/CDではバージョン固定を検討してください。公式リポジトリのREADMEでは、latestだけでなく特定バージョンのイメージを指定する例も示されています。検証時と本番時でツールのバージョンが変わると、設定の解釈や拡張機能の挙動差に気付きにくくなります。(GitHub)
migrationsettings.jsonで必ず確認する設定
Data Migration Toolの中心はmigrationsettings.jsonです。このファイルで、どこから読み、どこへ書き込むかを定義します。公式ドキュメントでも、Source、Sink、SourceSettings、SinkSettingsを使った設定例が示されています。(Microsoft Learn)
JSONファイルをAzure Cosmos DB for NoSQLへ移す場合の基本例は次のとおりです。
{
"Source": "JSON",
"Sink": "Cosmos-nosql",
"SourceSettings": {
"FilePath": "C:\\dmt\\data\\products.json"
},
"SinkSettings": {
"ConnectionString": "AccountEndpoint=https://<account>.documents.azure.com:443/;AccountKey=<key>;",
"Database": "datamigration",
"Container": "products",
"PartitionKeyPath": "/categoryId",
"RecreateContainer": false,
"IncludeMetadataFields": false,
"BatchSize": 100,
"WriteMode": "UpsertStream"
}
}実務では、サンプルのまま実行するのではなく、次の項目を必ずレビューしてください。
| 設定 | 確認ポイント | 失敗例 |
|---|---|---|
Source / Sink | 拡張機能名と一致しているか | Cosmos-nosqlの大文字小文字や名称を誤る |
ConnectionString | AccountKeyを含む接続文字列を安全に管理しているか | 設定ファイルをGitにコミットする |
UseRbacAuth | RBACで接続する場合にAccountEndpointなどを指定しているか | RBACを有効にしたのにCLI認証や権限が不足する |
Database / Container | 移行先のデータベース・コンテナーが正しいか | 検証用コンテナーではなく本番コンテナーへ投入する |
PartitionKeyPath | 新規コンテナー作成時のパーティションキーが適切か | /idを安易に使い、負荷が偏る |
PartitionKeyPaths | 階層型パーティションキーを使う場合に指定が妥当か | 複数パスの意味を確認せず作成する |
RecreateContainer | 既存コンテナーを削除・再作成してよいか | 本番データ入りコンテナーを消してしまう |
IncludeMetadataFields | _etagや_tsなどのメタデータを含める必要があるか | アプリが不要な内部項目まで取り込む |
Query | ソース側で移行対象を絞るか | 全件移行のつもりでないのに条件なしで実行する |
BatchSize | 書き込み単位とRU消費を調整しているか | 大きすぎてスロットリングやリトライが増える |
WriteMode | Insert、Upsertなどの挙動を理解しているか | 既存データを上書きするつもりがなかったのにUpsertする |
DisableSslValidation | 開発用途以外で無効化していないか | 本番接続で証明書検証を無効にする |
Cosmos DB拡張機能では、RBAC認証、プロキシ、Bulk Execution、Always Encrypted、PartitionKeyPath、RecreateContainer、BatchSize、WriteMode、ConnectionMode、DisableSslValidationなど多くの設定が用意されています。特にDisableSslValidationは開発用途の設定であり、本番環境で使うべきではありません。(GitHub)
複数ソース移行ではOperationsを使う
複数のJSONファイルや複数コンテナーへの移行を1回の実行でまとめたい場合は、Operations配列を使います。公式ドキュメントでは、products.json、customers.json、orders.jsonのように複数のソース設定とシンク設定を1つのmigrationsettings.jsonにまとめる例が示されています。(Microsoft Learn)
実務でOperationsを使う場合は、次の点を事前に決めてください。
- コンテナーごとのパーティションキー
- 親子関係があるデータの移行順序
- 失敗時にどこから再実行するか
- 各Operationの移行件数と検証方法
- 1回の実行でまとめる範囲と、分割実行する範囲
特に注文データ、顧客データ、商品データのように参照関係がある場合、単にファイルを投入するだけでは整合性を保証できません。Cosmos DB自体にはリレーショナルデータベースの外部キー制約のような仕組みはないため、参照先の存在確認や移行後の整合性チェックはアプリケーション側、検証スクリプト、または運用手順で補う必要があります。(Microsoft Learn)
MongoDBからの移行で失敗しやすいポイント
MongoDBからAzure Cosmos DB for NoSQLへ移す場合、最も危険なのは「JSONドキュメントだからそのまま移せる」と考えることです。公式更新で明確になったように、MongoDBからAzure Cosmos DBへ移行する場合はクロスAPI移行として扱い、データモデル、スキーマ、インデックスの変更を検討する必要があります。(Microsoft Learn)
見直すべき項目
| 項目 | 確認内容 |
|---|---|
_idとid | Cosmos DB for NoSQLではidが重要。既存の_idをどう扱うか決める |
| パーティションキー | MongoDBのシャードキーや検索条件をそのまま採用せず、アクセスパターンから設計する |
| インデックス | MongoDBのインデックス設計とCosmos DBのインデックス設計は同じではない |
| クエリ | MongoDBクエリとCosmos DB for NoSQLのSQLクエリは別物として検証する |
| 埋め込みと参照 | 1アイテムに無制限に増える配列を埋め込まない |
| アプリ互換性 | ドライバー、SDK、接続方式、エラーハンドリングを見直す |
| 移行後検証 | 件数だけでなく、主要クエリの結果とレスポンス時間を比較する |
MongoDB互換アプリを大きく作り替えずに動かしたい場合は、Azure DocumentDBの検討が必要です。一方、Azure Cosmos DB for NoSQLへ移す場合は、非正規化、埋め込み、参照、パーティション設計を含む再設計プロジェクトとして扱うべきです。
管理者が確認すべきセキュリティと権限
移行では一時的に強い権限を持つ接続文字列やキーを扱いがちです。ConnectionStringを使う場合、AccountKeyが含まれるため、設定ファイルの保管、ログ出力、CI/CDのシークレット管理に注意してください。Cosmos拡張機能では、UseRbacAuthをtrueにしてRBAC認証を使う設定も用意されています。(GitHub)
実務では次の方針にすると安全です。
- 移行専用の権限を用意し、移行後に削除または無効化する
migrationsettings.jsonをGitに含める場合は、接続情報を別管理にする- Dockerイメージ内に設定ファイルやキーを焼き込まない
- CI/CDではシークレットストアや環境変数を使う
- 本番移行後にAccountKeyのローテーションを検討する
- 開発用の
DisableSslValidationを本番設定に残さない - Always Encryptedを使う場合は、RBACとKey Vault権限まで含めて検証する
Docker・GitHub Actionsで展開する際の注意点
Data Migration Toolはコンテナー化された環境やGitHub Actionsの一部として実行できると説明されています。これは、定期的な検証データ投入や移行リハーサルを自動化したいチームには便利です。(Microsoft Learn)
ただし、本番移行を自動化する場合は、次のような運用ルールが必要です。
| 項目 | 推奨対応 |
|---|---|
| イメージタグ | 本番移行ではlatestではなく検証済みバージョンを使う |
| 設定ファイル | /configにマウントし、環境ごとに分離する |
| データファイル | /dataにマウントし、移行後に不要データを削除する |
| ログ | 成功・失敗・件数・リトライを保存する |
| 再実行 | UpsertかInsertかを決め、再実行時の重複・上書きを確認する |
| ネットワーク | Private Endpoint、プロキシ、ファイアウォール制限を事前に確認する |
| 承認 | 本番実行前に変更管理やメンテナンスウィンドウを通す |
CI/CDに組み込む場合でも、移行は「デプロイ作業」ではなく「データ変更作業」です。アプリケーションのビルドと同じ感覚で自動実行すると、意図しない上書きや削除が起きる可能性があります。
移行前に実施すべき検証手順
Azure Cosmos DB Data Migration Toolを使う前に、いきなり本番データを移行するのは避けてください。次の順序で進めると、設定ミスや設計ミスを早い段階で発見できます。
| 手順 | 作業内容 | 合格基準 |
|---|---|---|
| 事前整理 | 移行元、移行先API、対象データ、件数、容量を洗い出す | 移行対象と除外対象が明文化されている |
| 設計確認 | パーティションキー、id、インデックス、TTL、暗号化を確認する | アクセスパターンと設計が対応している |
| 小規模検証 | 数百件から数千件程度で移行する | 件数、代表クエリ、アプリ動作が一致する |
| 負荷検証 | 本番に近い件数でRU消費と処理時間を見る | スロットリングや失敗時の挙動を把握している |
| リハーサル | 本番手順と同じコマンド・設定で実行する | 手順書だけで再現できる |
| 本番移行 | メンテナンス時間内に実行し、ログを保存する | 移行完了、検証完了、切り戻し判断が可能 |
| 移行後確認 | 件数、サンプルデータ、主要クエリ、アプリログを確認する | 利用者影響がない状態で切り替えできる |
件数チェックだけでは不十分です。Cosmos DBでは、パーティションキーの偏り、クエリのRU消費、アイテムサイズ、インデックス設計が運用コストに直結します。検証では、代表的な読み取り・書き込みパターンを実行し、移行後の性能も確認してください。
実務でよくある疑問
Azure Cosmos DB Data Migration ToolはGUIツールですか？
現在の公式ドキュメントでは、オープンソースのコマンドラインアプリケーションとして説明されています。GitHub Releasesから各OS向けのファイルを取得してdmtコマンドで実行するか、Dockerイメージで実行する形が基本です。(Microsoft Learn)
MongoDB拡張機能があるなら、MongoDBからAzure Cosmos DBへ簡単に移行できますか？
データ転送の入口としてMongoDB拡張機能を使えるケースはありますが、MongoDBアプリの互換性やデータモデルをそのまま維持できるという意味ではありません。MongoDB wire protocol互換性を重視する場合はAzure DocumentDB向けの移行ガイダンスを確認し、Azure Cosmos DB for NoSQLへ移す場合はクロスAPI移行として再設計してください。(Microsoft Learn)
RecreateContainerは便利なので有効にしてよいですか？
検証環境では便利ですが、本番では慎重に扱うべきです。RecreateContainerは既存コンテナーを削除・再作成して、インポートデータだけを残す目的の設定です。誤って本番コンテナーに対して有効にすると、既存データを失うリスクがあります。(GitHub)
Dockerのlatestタグを本番で使ってもよいですか？
動作確認だけなら始めやすい方法ですが、本番移行では検証済みバージョンを固定する方が安全です。公式リポジトリでは、latestだけでなく特定バージョンのDockerイメージを指定する例も示されています。(GitHub)
複数コンテナーをまとめて移行できますか？
できます。migrationsettings.jsonにOperations配列を使うことで、複数のデータ転送操作を1回の実行コマンドで実行できます。ただし、コンテナーごとのパーティションキー、移行順序、失敗時の再実行方法は事前に決めておく必要があります。(Microsoft Learn)
移行前チェックリスト
本番作業に入る前に、次の項目を確認してください。
| チェック | 確認内容 |
|---|---|
| 移行先API | Azure Cosmos DB for NoSQL、Table、MongoDB系、Azure DocumentDBのどれかを明確にした |
| データモデル | RDBやMongoDBの構造をそのまま移さず、Cosmos DB向けに設計した |
| パーティションキー | 主要クエリ、書き込み量、データ分布を見て決めた |
| 設定ファイル | Source、Sink、Database、Container、PartitionKeyPathをレビューした |
| 認証 | ConnectionStringまたはRBACの方式を決め、不要な権限を残さない |
| 実行環境 | DockerまたはCLIのバージョンを検証環境と本番で合わせた |
| セキュリティ | 接続文字列、キー、設定ファイルを安全に保管した |
| 検証 | 件数、主要クエリ、アプリ動作、RU消費を確認した |
| ロールバック | 失敗時に戻す手順、バックアップ、切り戻し条件を用意した |
| 移行後作業 | キーのローテーション、不要ファイル削除、権限削除を計画した |
まとめ：まず移行先のAPIを決め、設定ファイルを小さく検証する
Azure Cosmos DB Data Migration Toolは、Azure Cosmos DBへのデータ移行を効率化できる便利なCLIツールです。ただし、2026年5月15日時点で特に重要なのは、MongoDB互換性を求める移行と、Azure Cosmos DB for NoSQLへのクロスAPI移行を混同しないことです。
管理者や開発者が最初に行うべきことは、ツールを実行することではありません。まず、移行先がAzure Cosmos DB for NoSQLなのか、Azure DocumentDBなのか、Table APIなのかを決めてください。そのうえで、migrationsettings.jsonを最小構成で作り、検証環境に少量データを移して、件数・クエリ・アプリ動作・RU消費を確認します。
本番移行では、Dockerイメージのバージョン固定、接続情報の保護、RecreateContainerやWriteModeの確認、ロールバック手順の準備が欠かせません。Data Migration Toolは移行を簡単に始めるための道具ですが、成功させる鍵は、移行前の設計確認と移行後の検証にあります。
コメント