Azure DocumentDB Migration Extension in Visual Studio Code は、MongoDB から Azure DocumentDB への移行作業を VS Code 上で進められる拡張機能です。2026年6月に一般提供（GA）となり、移行ジョブの作成、実行、監視、オンライン移行のカットオーバーまでを、開発者になじみのある Visual Studio Code から扱いやすくなりました。特に確認すべきポイントは、オンライン移行では Change Stream が必要なこと、DMS とネットワーク設定が移行成功の鍵になること、カットオーバー前の検証を省略しないことです。(マイクロソフト Azure)
Azure DocumentDB Migration Extension in Visual Studio Codeとは
Azure DocumentDB Migration Extension は、Visual Studio Code から MongoDB ワークロードを Azure DocumentDB へ移行するための拡張機能です。オンプレミス、Azure 上の VM、他クラウド、MongoDB Atlas などの MongoDB 互換ソースから、Azure DocumentDB への移行を支援します。(Microsoft Learn)
従来、データベース移行では、移行ツールの準備、ネットワーク経路の確認、移行ジョブの監視、切り替え手順の作成などを個別に管理する必要がありました。この拡張機能では、VS Code の画面から次の作業をまとめて進められます。
- 移行前アセスメントの実行
- 移行対象のデータベース、コレクションの選択
- オンライン移行またはオフライン移行の選択
- Azure Database Migration Service（DMS）の選択または作成
- パブリック接続、プライベート接続の設定
- 移行ジョブの監視
- オンライン移行時のカットオーバー操作
Microsoft の公式情報では、この拡張機能は追加の移行インフラを用意せずに、Azure 管理リソース上で移行ジョブを実行できる点が特徴として説明されています。(Microsoft Learn)
今回のGAで何が変わったのか
今回のポイントは、Azure DocumentDB Migration Extension のオンライン移行機能が一般提供になったことです。パブリックプレビュー段階から、より本番移行で使いやすい形に改善されています。(Microsoft for Developers)
主な変更点は次の通りです。
| 変更点 | 内容 | 実務上の意味 |
|---|---|---|
| 一般提供（GA） | プレビューではなく本番利用を前提に使いやすい段階へ | 本番移行計画の候補に入れやすくなる |
| 大規模移行への対応改善 | 多数のコレクション、大量ドキュメントを扱うケースでの信頼性を改善 | 大規模 MongoDB 環境でも検証対象にしやすい |
| プライベート接続対応の強化 | 複雑な VNet、ハブスポーク、ファイアウォール構成への対応を拡充 | セキュリティ要件が厳しい企業環境で検討しやすい |
| リトライ、チェックポイント改善 | 一時的なネットワーク断や部分的な失敗からの再開性を改善 | 長時間移行時の失敗リスクを下げやすい |
| Change Stream 同期の強化 | カーソル期限切れ、再開トークン、長時間同期への耐性を改善 | オンライン移行の整合性を保ちやすい |
| UIとエラーメッセージ改善 | 大規模移行時のダッシュボード表示や診断性を改善 | トラブル時の原因特定がしやすい |
ただし、GAになったからといって「設定不要で安全に移行できる」という意味ではありません。移行元 MongoDB の機能互換性、ネットワーク到達性、権限、Change Stream、oplog、カットオーバー手順は、従来通り事前確認が必要です。
影響を受ける利用者とシステム
今回の更新で特に影響を受けるのは、MongoDB または MongoDB 互換データベースを Azure DocumentDB へ移行しようとしている開発チーム、インフラ管理者、クラウド管理者です。
影響が大きいケース
次のような環境では、今回の拡張機能を検討する価値があります。
| 対象 | 具体例 | 確認すべきこと |
|---|---|---|
| MongoDB を Azure へ移行したい開発チーム | 既存アプリのデータストアを Azure DocumentDB に移す | アプリのクエリ、インデックス、接続文字列の変更範囲 |
| オンプレミス MongoDB を運用している企業 | データセンター内の MongoDB を Azure に集約 | VPN、ExpressRoute、ファイアウォール、DNS |
| MongoDB Atlas など他クラウド利用中の組織 | マルチクラウド整理や Azure 統合を進める | 移行元の Change Stream、ネットワーク許可、移行期間 |
| セキュアな閉域移行が必要な組織 | パブリックIPを使わずに移行したい | Private connectivity、VNet ピアリング、CIDR 重複 |
| 大量コレクションを持つ環境 | 数百コレクション、大量ドキュメントの移行 | 事前アセスメント、試験移行、移行時間の見積もり |
一方、単発の小規模データ移行や、完全停止できる検証環境では、従来の mongodump / mongorestore などのネイティブ MongoDB ツールの方がシンプルな場合もあります。Microsoft Learn でも、全体移行には mongodump / mongorestore、一部データの移行には mongoexport / mongoimport という選択肢が示されています。(Microsoft Learn)
オンライン移行とオフライン移行の違い
Azure DocumentDB Migration Extension では、オンライン移行とオフライン移行を選択できます。どちらを選ぶかで、停止時間、準備項目、リスクが変わります。
| 移行方式 | 特徴 | 向いているケース | 注意点 |
|---|---|---|---|
| オンライン移行 | 初期データコピー後も、移行中の変更を Change Stream で同期する | 本番システムの停止時間を短くしたい | Change Stream と十分な oplog が必要 |
| オフライン移行 | 移行開始時点のスナップショットをコピーする | 停止時間を確保できる、データ更新が少ない | 移行開始後の更新はコピーされない |
本番環境では「止めたくないからオンライン移行」と考えがちですが、オンライン移行には前提条件があります。公式ドキュメントでは、オンライン移行を成功させるには移行元 MongoDB で Change Stream が有効である必要があり、Change Stream がない場合は初期移行後の変更を捕捉できないと説明されています。(Microsoft Learn)
つまり、判断基準は「止められるか」だけではありません。
オンライン移行を選ぶ前に、少なくとも次を確認してください。
- 移行元 MongoDB で Change Stream が利用できるか
- 移行期間中の変更を保持できるだけの oplog サイズがあるか
- 移行対象コレクションへの書き込み量がどの程度か
- カットオーバー時に一時的に書き込みを止められるか
- 移行後に件数、サンプルデータ、インデックスを検証する時間を確保できるか
管理者が事前に確認すべき設定
管理者が最初に見るべきなのは、VS Code 拡張機能のインストール可否ではなく、Azure 側の権限、DMS、ネットワーク、認証方式です。ここを曖昧にしたまま進めると、移行ジョブ作成や接続確認の段階で止まりやすくなります。
必要な前提条件
Microsoft Learn では、Azure サブスクリプション、既存の Azure DocumentDB クラスター、Azure DocumentDB Migration Extension のインストールが前提として示されています。また、移行元 MongoDB には readAnyDatabase と clusterMonitor 権限を持つユーザー、移行先 Azure DocumentDB には createCollection、dropCollection、createIndex、insert、listCollections などの権限が必要です。(Microsoft Learn)
管理者は、以下のチェックリストを使うと抜け漏れを減らせます。
| 確認項目 | 確認内容 | よくある失敗 |
|---|---|---|
| Azure サブスクリプション | 移行先 DocumentDB と DMS を作成・操作できるか | 権限不足でジョブを作れない |
| Azure DocumentDB クラスター | 移行先が作成済みか、接続文字列を取得できるか | ターゲット未準備のまま移行作業を開始する |
| Microsoft.DataMigration | リソースプロバイダーが登録済みか | DMS 作成時に失敗する |
| DMS 権限 | Azure Database Migration Service Contributor などが付与されているか | DMS を選択・作成できない |
| ネットワーク | パブリック接続かプライベート接続か決めているか | ファイアウォール、DNS、VNet で詰まる |
| 認証方式 | 移行ジョブで使う認証が対応しているか | Entra ID 前提で設計してしまう |
特に重要なのは、移行ジョブでは Microsoft Entra ID 認証が現時点でサポートされておらず、ネイティブ DocumentDB 認証を使う必要がある点です。(Microsoft Learn)
開発者が確認すべき移行前アセスメント
開発者にとって最も重要なのは、「データがコピーできるか」よりも「アプリケーションが移行後に正しく動くか」です。Azure DocumentDB は MongoDB 互換をうたっていますが、すべての機能、クエリ、インデックス、運用前提が完全に同じとは限りません。
Azure DocumentDB Migration Extension のアセスメント機能では、未対応の MongoDB 機能、コマンド、クエリ構文、インデックス種別などを検出し、アカウント、データベース、コレクション単位でレポートを生成できます。結果は Critical、Warning、Informational などに分類され、優先順位を付けやすくなっています。([Visual Studio Marketplace][5])
アセスメント結果で見るべきポイント
アセスメントを実行したら、次の観点で確認します。
| 観点 | 見るべき内容 | 対応例 |
|---|---|---|
| Critical | 移行後に動作しない可能性が高い機能 | クエリ修正、設計変更、移行対象除外 |
| Warning | 性能や互換性に影響する可能性 | インデックス見直し、負荷試験 |
| Informational | 環境情報、制限、参考情報 | 移行計画書に反映 |
| インデックス | 移行先で期待通り作成されるか | 重要クエリの実行計画を確認 |
| コレクション数・サイズ | 移行時間、DMS、ターゲット性能の見積もり | 代表データでリハーサル |
ここでありがちな失敗は、アセスメントを「エラーが出るかどうかの確認」として一度だけ実行し、結果を開発タスクに落とし込まないことです。Critical や Warning が出た場合は、修正担当、期限、検証方法を決めてから本番移行へ進むべきです。
移行ジョブ作成時の実務ポイント
Azure DocumentDB Migration Extension の移行ウィザードでは、主に次の流れで移行ジョブを作成します。
| 手順 | 作業内容 | 確認ポイント |
|---|---|---|
| ソース接続 | VS Code の DocumentDB Connections に移行元 MongoDB を追加 | 接続文字列、TLS、認証情報 |
| 移行拡張機能の起動 | 接続を右クリックし Data Migration を選択 | 正しい接続を選んでいるか |
| ジョブ作成 | ジョブ名、移行方式、接続方式を選択 | Online / Offline、Public / Private |
| ターゲット選択 | Azure DocumentDB アカウントと接続文字列を指定 | ファイアウォール許可 |
| DMS 選択 | 既存 DMS または新規 DMS を選択 | 同一リージョン、権限 |
| 接続設定 | パブリックまたはプライベート接続を構成 | IP許可、VNet、CIDR |
| コレクション選択 | 移行対象コレクションを選ぶ | 作成後に追加できない点に注意 |
| 確認・開始 | 内容を確認して移行開始 | 誤ったDBやコレクションを選んでいないか |
公式ドキュメントでは、移行ジョブ作成後にコレクション一覧を追加できないため、含めるべきコレクションを事前にすべて選択するよう注意されています。(Microsoft Learn)
小さな検証では問題になりにくいものの、本番では「関連コレクションを1つ選び忘れた」だけでアプリの一部機能が動かなくなることがあります。ユーザー、注文、商品、セッション、監査ログのように、アプリ側で暗黙に依存しているコレクションも棚卸ししてください。
パブリック接続とプライベート接続の選び方
接続方式は、移行の成否を左右します。Azure DocumentDB Migration Extension では Public と Private を選択できます。
| 接続方式 | 使うべきケース | 主な作業 | 注意点 |
|---|---|---|---|
| Public | 移行元・移行先がパブリックIP経由で到達可能 | DMS の静的IPをファイアウォール許可 | セキュリティポリシー上許可されるか確認 |
| Private | 移行元または移行先がプライベートIPのみ | VNet ピアリング、CIDR、PowerShell スクリプト実行 | DNS、NSG、ルート、CIDR重複に注意 |
パブリック接続では、ウィザードに表示される DMS の静的 IP アドレスを、移行元 MongoDB と Azure DocumentDB のファイアウォール許可リストに追加します。(Microsoft Learn)
プライベート接続では、DMS が移行ジョブごとに専用の一時的な仮想ネットワークを作成し、移行元・移行先の VNet とピアリングします。セキュリティ面では有利ですが、CIDR 重複、DNS、NSG、ルーティング、ハブスポーク構成の制約を確認する必要があります。特にプライベート接続では、1つの仮想ネットワークで同時に実行できるアクティブな移行ジョブは1つという制約があります。(Microsoft Learn)
オンライン移行時のカットオーバーで失敗しやすいポイント
オンライン移行では、初期データコピーの後、Change Stream によって移行中の更新を追従します。公式ブログでは、移行は「Initial Bulk Copy」と「Change Stream Sync」の2段階で進み、ターゲットが追いついたタイミングでカットオーバーする流れと説明されています。(Microsoft for Developers)
ただし、カットオーバーは単にボタンを押せば終わる作業ではありません。次の順序を守ることが重要です。
| 順序 | 作業 | 判断基準 |
|---|---|---|
| 事前確認 | 初期ロード完了を確認 | すべての対象コレクションで初期コピーが完了 |
| 書き込み停止 | 移行元への新規書き込みを止める | アプリ、バッチ、管理ツールからの書き込みも停止 |
| 同期待ち | レプリケーション差分が小さくなるまで待つ | Replication Changes Played が安定 |
| データ検証 | 件数、サンプル、重要データを照合 | 期待値と一致している |
| 接続先変更 | アプリの接続文字列を Azure DocumentDB に変更 | 読み取り、書き込み、主要機能の動作確認 |
| 監視 | エラー、遅延、スループットを確認 | 異常があれば即時判断できる体制 |
公式ドキュメントでも、ソースとターゲットが同期していることを検証せずにカットオーバーするとデータ損失につながる可能性があると注意されています。(Microsoft Learn)
実務では、カットオーバー直前に「まだ書き込みが残っていた」「夜間バッチが動いていた」「管理者が手動更新していた」というケースが起きがちです。アプリ本体だけでなく、バッチ、ETL、管理画面、外部連携、運用スクリプトも停止対象に含めてください。
展開時に決めておくべき運用ルール
VS Code 拡張機能として提供されるため、開発者が簡単に試せる一方で、組織利用ではルール整備が必要です。特に本番データを扱う場合、誰でも移行ジョブを作れる状態は避けるべきです。
組織で決めるべきルール
| 項目 | 推奨ルール | 理由 |
|---|---|---|
| 拡張機能の利用者 | 移行担当者に限定 | 誤操作や不要な接続情報の拡散を防ぐ |
| 接続文字列の扱い | 個人メモやチャットに貼らない | 資格情報漏えいを防ぐ |
| DMS 作成権限 | 管理者または移行リードに限定 | 不要なリソース作成を防ぐ |
| 本番移行の実行 | 承認済み手順書に基づいて実施 | カットオーバー時の混乱を防ぐ |
| ログの保管 | トラブル調査用に場所を把握 | 障害時の原因分析に必要 |
| テレメトリ | 組織ポリシーに従って設定 | 利用データ送信の要否を管理 |
Visual Studio Marketplace の情報では、VS Code の利用データ送信を無効にしたい場合は telemetry.enableTelemetry を false に設定できると説明されています。組織のプライバシー・監査ポリシーに応じて確認しておきましょう。([Visual Studio Marketplace][5])
移行前に作っておきたいチェックリスト
本番移行では、ツールの使い方よりも「準備が完了しているか」の方が重要です。以下のチェックリストを使うと、管理者と開発者の認識をそろえやすくなります。
| フェーズ | チェック項目 |
|---|---|
| 計画 | 移行対象DB、コレクション、除外対象を一覧化した |
| 計画 | オンライン移行かオフライン移行かを決めた |
| 計画 | カットオーバー日時、停止時間、判断者を決めた |
| アセスメント | 移行前アセスメントを実行した |
| アセスメント | Critical / Warning の対応方針を決めた |
| 権限 | MongoDB 側の読み取り・監視権限を用意した |
| 権限 | Azure DocumentDB 側の作成・挿入・インデックス権限を確認した |
| Azure | Microsoft.DataMigration が登録済みである |
| Azure | DMS のリージョンと権限を確認した |
| ネットワーク | Public / Private の接続方式を決めた |
| ネットワーク | ファイアウォール、DNS、NSG、CIDR を確認した |
| リハーサル | 代表データで試験移行を実施した |
| 検証 | 件数比較、サンプル比較、インデックス確認の方法を用意した |
| アプリ | 接続文字列の変更手順を確認した |
| 運用 | 切り戻しではなく、停止判断・延期判断の基準を決めた |
特に「切り戻し」を簡単に考えないことが重要です。Microsoft Learn のベストプラクティスでも、カットオーバーは慎重に計画すべきで、書き込み移行後のロールバックを前提にしないよう注意されています。(Microsoft Learn)
すぐに取るべき次のアクション
Azure DocumentDB Migration Extension in Visual Studio Code のGAは、MongoDB から Azure DocumentDB への移行を検討しているチームにとって、移行計画を具体化しやすくする更新です。特に、VS Code 上でアセスメントから移行ジョブ管理まで進められるため、開発者と管理者が同じ画面を見ながら移行作業を進めやすくなります。
まずは本番移行ではなく、次の順で確認するのが安全です。
- VS Code に Azure DocumentDB Migration Extension を導入する
- 移行元 MongoDB に対して移行前アセスメントを実行する
- Critical / Warning の内容を開発タスクに分解する
- 代表データで試験移行を行い、移行時間と性能を測る
- ネットワーク、DMS、権限、カットオーバー手順を確定する
- 本番移行は低トラフィック時間帯に、検証手順付きで実施する
GAになったことで検討しやすくなった一方、成功の鍵はツール導入そのものではなく、移行前アセスメント、ネットワーク設計、Change Stream確認、検証可能なカットオーバー手順にあります。MongoDB ワークロードを Azure DocumentDB へ移す予定があるなら、まずはアセスメントを実行し、移行対象とリスクを見える化するところから始めるのが現実的です。
[5]: https://marketplace.visualstudio.com/items?itemName=ms-azurecosmosdbtools.vscode-mongo-migration “
Azure DocumentDB Migration – Visual Studio Marketplace
“
コメント