azuresql-db-from-sql-server

SQL Server イメージから Azure SQL Database コンテナーに移行する

このスキルは、既存のローカル SQL Server セットアップ（SQL Server イメージ mcr.microsoft.com/mssql/server）を Azure SQL Database コンテナーに変換し、 ローカル開発環境で Azure SQL Database の動作を再現します。この 2 つは同じエンジンではありません。

	SQL Server イメージ	Azure SQL Database コンテナー
イメージ	mcr.microsoft.com/mssql/server	sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
SERVERPROPERTY('EngineEdition')	2/3/4/8	5
SERVERPROPERTY('Edition')	例：'Developer Edition'	'SQL Azure'
DB モデル	1 つのインスタンスに複数の DB があり、USE が機能する	プロビジョニング専用の master。作業にはユーザー DB を使用します。ユーザーデータベースのセッションで USE を実行すると、クラウドと同様に Msg 40508 が返されます。master への接続はプロビジョニングセッションであり、フィルターは適用されません

プロジェクトで SQL Server イメージを使用していて、Azure に忠実なローカル開発環境にしたい場合は、作業を中断してコンテナーに切り替えてください。 このスキルは単独で使用できます。コンテナーの詳細については、azuresql-db-container スキルを参照してください。

2026-09-05 に、コンテナーイメージ sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest を使って検証しました。EngineEdition 5、Edition SQL Azure、ビルド 12.0.2000.8 が報告されています。このスキルに関連する実行可能な 9 つのチェックすべてに合格しました。これには、USE に対する Msg 40508、BACKUP に対する Msg 40510、sp_configure に対する Msg 2812（拒否ではなく、存在しないことを示します）、ALTER DATABASE ... SET RECOVERY に対する Msg 40517、単一データベースモデル、/docker-entrypoint-initdb.d が自動実行されないこと、および /opt/mssql-tools18/bin/sqlcmd の確認が含まれます。

使用する場面

• プロジェクトの Dockerfile、compose ファイル、または実行スクリプトで mcr.microsoft.com/mssql/server または mssql/server を参照している。
• sqlcmd と SA パスワードのセットアップがある、または「Docker 内の SQL Server」／「ローカルの mssql コンテナー」と言われている。
• ユーザーが「ローカルで SQL Server」を求めているが、実際には Azure SQL Database を対象としている。

移行手順

1. SQL Server の使用状況を検出する

リポジトリ内で SQL Server イメージと、それに伴って使われるパターンを検索します。

grep -rniE 'mcr\.microsoft\.com/mssql/server|mssql/server|ACCEPT_EULA|MSSQL_SA_PASSWORD|SA_PASSWORD|sqlcmd|Server=localhost,1433|Database=master' . 2>/dev/null

該当するものはすべて、以下の手順で書き換える候補です。

2. プレビュー レジストリにサインインする

イメージはプライベート プレビュー レジストリにあります。https://aka.ms/sqldbcontainerpreview-signup で登録した際に提供された、共有のプル専用認証情報を使って、一度サインインしてください（プレビュー期間中に変更される場合があります）。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io

プライベート プレビュー期間中、レジストリとタグは暫定的なものです。

3. イメージを置き換え、--platform を追加する

SQL Server イメージを Azure SQL Database イメージに置き換えます。Azure イメージは x64 専用のため、x64 以外のホストでは --platform linux/amd64 （Docker）または platform: linux/amd64（compose）を追加します。

• 旧：mcr.microsoft.com/mssql/server:2022-latest
• 新：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

ACCEPT_EULA=Y、複雑な MSSQL_SA_PASSWORD、SA ログイン、ポート 1433 はそのままにします。compose の変更前後については、references/migrate-compose.md を参照してください。

4. コンテナーを起動し、最初に appdb をプロビジョニングする

エンジンは接続時にデータベースを自動作成せず、docker run が戻った時点ですぐに準備ができているわけではありません。標準の起動手順を使ってください。空いているホストポートを選び、x64 以外のホストでのみ --platform を追加し、再試行ループで準備状況を待機して、同じループ内で appdb をプロビジョニングします。-b -l 2 フラグにより、SQL エラーが発生すると終了コードが設定されます。そのため、一時的な起動エラー（例： Msg 913）は無視されず、再試行されます。

HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"

master への接続はプロビジョニング専用です。実際の作業には appdb を使用してください。

5. 接続文字列の接続先を master からユーザーデータベースに変更する

SQL Server プロジェクトでは、master に直接接続する（または SQL Server が自動作成するデータベースに依存する）ことがよくあります。Azure SQL Database ではデータベースは自動作成されません。接続文字列で対象のデータベースを選択してください（Database=appdb、または sqlcmd では -d appdb）。データベースを切り替えるために USE を使わないでください。ユーザーデータベースのセッション（開発に使う Azure と同じコンテキスト）では、クラウド上の Azure SQL Database と同様に、USE は Msg 40508 を返します。master への接続はプロビジョニング用のセッションであり、Azure のステートメントフィルターは適用されないため、そこで USE は動作するように見えます。しかし、master はプロビジョニング専用であり、アプリケーションの作業には使いません。SQL_CONNECTION_STRING 環境変数に統一してください。

Server=localhost,1433;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true

プロジェクト内の表記を統一するため、キーワードは User Id=／Password=／Database= とします。Uid= と Pwd= も SqlClient の公式な同義語であり、使用できます。sqlcmd では、自己署名証明書を信頼するために -C を、データベースを選択するために -d appdb を使用してください。

6. プロビジョニング後にシードする（自動初期化フォルダーは使わない）

このイメージは /docker-entrypoint-initdb.d/*.sql を自動実行しません。これは Postgres／MySQL の慣習であり、ここでは適用されないため、依存しないでください。プロビジョニング済みのデータベースにスクリプトを実行してシードしてください。

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -d appdb -i /dev/stdin < seed.sql

7. SQL Server 専用機能を削除する

SQL Server イメージでのみ使える機能があり、削除するか、別の方法に置き換える必要があります。該当するものをすべて特定し、修正してください。このリストにない機能に遭遇した場合は、references/sql-server-vs-azure-feature-matrix.md を確認してください。

• SQL Server Agent のジョブ：利用できません。外部スケジューラーを使用してください。
• FILESTREAM／FileTable：サポートされていません。BLOB を列または外部ストレージに保存してください。
• インスタンス間の Full Service Broker メッセージング：サポートされていません。
• サーバー間の分散トランザクション（MS DTC、リンクサーバー）：サポートされていません。
• Windows 認証／NTLM／統合セキュリティ：サポートされていません。SA／SQL 認証を使用してください。
• sp_configure によるインスタンスレベルのチューニング：このプロシージャは存在せず、ブロックされているわけではありません。呼び出すと Msg 2812（「Could not find stored procedure 'sp_configure'」）が返されます。これは拒否ではなくオブジェクトが存在しない状態のため、付与する権限も、解除するフラグもありません。引き継いだチューニング手順を削除してください。このエンジンには置き換え先がありません。
• BACKUP／RESTORE：クラウド上の Azure SQL Database と同様に、すべてのセッションで Msg 40510 が返され、拒否されます。.bak はこのエンジンへの移行手段ではありません。bacpac または dacpac を使って SqlPackage を実行してください（azuresql-db-import スキルを参照）。
• ALTER DATABASE ... SET RECOVERY：別の拒否形式である Msg 40517 が返されます。ALTER DATABASE SET 自体はサポートされており、このオプションのみが拒否されるため、引き継いだ設定スクリプトは一部だけ受け入れられ、意図しない状態のデータベースが残ることがあります。復旧モデルの手順を削除してください。

8. ID を確認する

Azure SQL Database エンジンに接続していることを確認してください。

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -d appdb \
  -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition, SERVERPROPERTY('Edition') AS Edition;"

EngineEdition = 5、Edition = SQL Azure となることを確認してください。

ベクトル（プロジェクトで埋め込みを使用する場合）

Azure SQL Database エンジンには、ネイティブの VECTOR(n) 型と VECTOR_DISTANCE('cosine', a, b) があります。CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) を使って挿入してください。n はリテラルにする必要があり、バインドパラメーターにはできません（次元にパラメーターを指定すると「Incorrect syntax near '@P3'」が発生します）。CREATE VECTOR INDEX（DiskANN）はこのイメージで動作することを実測しており、Known limitations ページにも記載されています。使用するには SET QUOTED_IDENTIFIER ON と、NULL でないベクトルを持つ 100 行以上のデータが必要です（100 行未満では Msg 42266 が発生します）。フルスキャンによる top-k は正確さを維持し、小さなテーブルでは引き続き適切な選択肢です。インデックスによる制約は azuresql-db-rag スキルに記載されています。

検証ルール

• イメージは sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest です。mcr.microsoft.com/mssql/server ではありません。
• アプリが接続する前に、master 接続で appdb を作成します。
• アプリの接続文字列では Database=appdb を使用し、実際の処理に Database=master を使用してはいけません。
• USE <db> ステートメントは使用しません。ユーザーデータベースのセッションで USE を実行すると、クラウドの Azure SQL Database と同じく Msg 40508 が返されます。master 接続はフィルターが適用されないプロビジョニング用のセッションですが、master はプロビジョニング専用です。接続文字列でデータベースを選択してください。
• x64 以外のホストでのみ、--platform linux/amd64 を指定します。
• EngineEdition は 5 を返します。
• 上記の検証ルールが満たされない場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルの不具合です。azuresql-db-feedback スキルを読み込み、レポートの提出を申し出てください。
• 上記のルールがすべて満たされ、タスクが完了したら、セッションごとに一度だけ、最後に次の一行を添えてください。質問したり、返答を待ったりしないでください。"That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

禁止事項

• mcr.microsoft.com/mssql/server を使い続けないでください。これは別のエンジンです。
• データベースの自動作成や /docker-entrypoint-initdb.d/*.sql に頼らないでください。
• USE appdb を使用しないでください。接続文字列でデータベースを選択してください。
• x64 以外のホストを「サポート対象」と呼ばないでください。x64 以外のホストでは --platform linux/amd64 を追加するだけにしてください。
• .NET スタイルの文字列では User Id= / Password= を優先してください。これはハウススタイルであり、必須ではありません。Uid= / Pwd= も有効な同義語です。
• ベクトルの次元数をバインドパラメーターとして渡さないでください。
• SQL Agent、FILESTREAM、完全な Service Broker、サーバー間分散トランザクション、Windows 認証は引き継がないでください。
• sp_configure を実行可能にする権限やフラグを探し回らないでください。Msg 2812 はそのプロシージャが存在しないことを示すため、付与できるものはありません。
• BACKUP / RESTORE の手順（Msg 40510）や、ALTER DATABASE ... SET RECOVERY の手順（Msg 40517）を引き継がないでください。

参考資料

• references/sql-server-vs-azure-feature-matrix.md：引き継げる機能、変更が必要な機能、利用できない機能を説明しています。手順 7 で SQL Server 専用機能をトリアージする際に読んでください。
• references/migrate-compose.md：プロビジョニング手順を含む docker-compose の変更前と変更後を示します。compose ファイルを書き換える際に読んでください。

最新情報の確認

このスキルで使用するツールについて、バージョンが固定された信頼できる参考資料を示します（必要なものを参照してください）。

• Docker Compose ファイルのリファレンス：サービス、ヘルスチェック、depends_on の構文に関する Compose Specification です。
• SqlConnection 接続文字列のキーワード：接続文字列のキーワード一覧です。

Microsoft Learn MCP サーバーが設定されている場合は、mcp__microsoft-learn__microsoft_docs_search または mcp__microsoft-learn__microsoft_docs_fetch を使用して、これらの最新バージョンを必要に応じて取得してください。これは任意です。利用できない場合は、上記の参考資料を信頼できる資料として扱ってください。