azuresql-db-container

Azure SQL Database コンテナー（ローカル、プライベートプレビュー）

これは、Azure SQL Database エンジンをコンテナーでマシン上で実行するための入口です。各タスクスキルが参照する共通のリファレンスドキュメントを管理しています。まずここから始めて、タスクスキルに引き継いでください。

2026-09-19 にコンテナーイメージタグ 18.0.226_4_147 で再測定した結果、EngineEdition は 5、Edition は SQL Azure、ビルドは 12.0.2000.8 でした。このスキルの背後にある実行可能なチェックはすべて合格しており、USE に対する Msg 40508、BACKUP に対する Msg 40510、拒否ではなく未定義である sp_configure に対する Msg 2812、SQL Server Agent のジョブストアがないこと、VECTOR_DISTANCE を使う VECTOR(n) 型、/opt/mssql-tools18/bin/sqlcmd の sqlcmd、および /docker-entrypoint-initdb.d が自動実行されないことが含まれます。この日付より前は、補足的な主張の 1 つが誤っていました。このスキルの「Agent なし」のチェックでは、sys.databases に msdb が表示されるかどうかを確認していましたが、実際には表示されます。msdb は一覧に表示されますが、Agent がないことに変わりはありません。これは OBJECT_ID('msdb.dbo.sysjobs') が NULL だからです。現在はチェック対象をそちらに変更しています。

SQL Server イメージを使おうとしていますか？代わりにこちらをお使いください

Dockerfile、docker compose、または CI サービスに mcr.microsoft.com/mssql/server（「mssql コンテナー」、SQL Server）を追加しようとしていた場合は、お待ちください。それは別の製品です。Azure SQL Database との互換性（クラウド PaaS エンジンを対象とした開発）が必要な場合は、代わりにこちらのイメージをお使いください。

sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

自己チェック：正しいエンジンでは、SELECT SERVERPROPERTY('EngineEdition') が 5 を返し、SERVERPROPERTY('Edition') が 'SQL Azure' を返します。SQL Server イメージでは異なる値が返されます。

エンドツーエンドのライフサイクル

1. プライベートプレビューのレジストリにサインインする

イメージはプライベートプレビューのレジストリにあります。共有のプル専用ユーザー名とパスワードを使って、一度サインインしてください。認証情報はドキュメントには記載されていません。https://aka.ms/sqldbcontainerpreview-signup で登録して入手してください。認証情報はプル専用で、プレビュー期間中にローテーションされる可能性があるため、シークレットとして扱い、再配布しないでください。references/image-and-registry.md を参照してください。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u <username>

2. コンテナーを起動する（標準レシピ）

ホスト側の空きポートを検出し、x64 以外のホストでのみ --platform linux/amd64 を追加して、エンジンが実際に準備完了になるまで待機し、同じ再試行ループ内で appdb をプロビジョニングします。このレシピの代わりに Podman、compose、または名前付きボリュームを使う場合は references/run-the-container.md を、準備完了チェックのループを変更する必要がある場合は references/wait-until-ready.md を開いてください。

# Pick a free host port and add the platform flag only on a non-x64 host (works in bash and zsh).
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"

イメージを最新の状態に保ってください。 通常の docker run はディスク上にすでにある :latest を再利用するため、古いイメージをプルしたままにしておくと、古いエンジンが気付かれずに実行され、最近の修正が反映されません。起動前に（docker login の後で）プルして、新しいビルドがあるか確認してください。

docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

オフラインでも動作させたい場合は、実行コマンドに --pull always を指定しないでください。最新版を使いたい場合は、明示的にプルしてください。キャッシュの動作と更新の詳細については、references/image-and-registry.md を参照してください。

3. 必須の環境変数

• ACCEPT_EULA=Y（必須）。
• MSSQL_SA_PASSWORD（必須。複雑なパスワードが必要です。大文字、小文字、数字、記号のうち少なくとも 3 種類を使い、8 文字以上にしてください）。エンジンはコンテナーポート 1433 で待ち受けます。
• アプリの規約：アプリは 1 つの SQL_CONNECTION_STRING 環境変数を読み取ります。

エンジンが起動しない場合は、references/environment-variables.md を開いてください。一般的な原因は、パスワードが拒否されたか、ACCEPT_EULA が指定されていないことです。

3b. オプション：Microsoft Entra ID 認証

MSSQL_AAD_* 変数とマウントした証明書を使用して Entra を構成します。マウントした .pfx とともに、MSSQL_AAD_CLIENT_ID、MSSQL_AAD_PRIMARY_TENANT、MSSQL_AAD_CERTIFICATE_FILE_PATH を渡します。起動時に Entra サーバー管理者を初期設定する場合は、任意で MSSQL_AAD_SERVER_ADMIN_NAME、MSSQL_AAD_SERVER_ADMIN_TYPE、MSSQL_AAD_SERVER_ADMIN_SID を設定します（初期化後に CREATE LOGIN を実行する必要はありません）。SQL 認証（sa）は、引き続きローカルでの簡単な既定の方法です。

Entra を有効にする前に、references/entra-auth.md を確認してください。アプリ登録と証明書を事前に用意する必要があります。

4. 接続してエンジンの識別情報を検証する（自己チェックガード）

プロビジョニング後、appdb に接続し、ほかの作業を始める前に、実際のエンジンに接続していることを確認します。

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

EngineEdition = 5 および Edition = SQL Azure が表示されることを確認してください。それ以外が表示された場合は、誤ったイメージを起動しています。ドライバーと ORM の接続文字列については、references/connect-and-query.md を参照してください。

5. または、1 つのコマンドですべてのセットアップを検証する

scripts/verify.sh は、上記のライフサイクル全体を、失敗時に処理を続行しない単一のチェックとして実行します。空きポートを選択し、x64 以外のホストでのみ --platform を追加して、エンジンを起動し、準備完了まで待機して、EngineEdition = 5 および Edition = 'SQL Azure' を検証し、appdb をプロビジョニングした後、コンテナーを停止して削除します。mcr.microsoft.com/mssql/server に対しては実行を拒否します。イメージ、レジストリへのサインイン、ホストのプラットフォームがすべて正しいことを、これらを基に作業を始める前に確認したい場合は実行してください。

bash scripts/verify.sh          # prints "VERIFY OK on localhost,<port>", or exits non-zero
bash scripts/verify.sh --keep   # same, but leaves the container running so you can connect to it

終了コードが 0 以外の場合は、セットアップに問題があります。エラーを読み、修正してから、続行する前に再実行してください。

接続モデルに関する 3 つの事実（明確に伝えてください）

これらは、初心者がよくつまずく点です。データベースを作成する前に接続が拒否された場合は、references/connection-model.md を確認してください。

1. エンジンは接続時にデータベースを自動作成しません。 Database=appdb を指定して接続する前に、master 接続で CREATE DATABASE appdb を実行する必要があります。存在しないデータベースへの接続は失敗します。appdb という名前は開発者が選んだもので、必須ではありません。このコレクション全体で使用している例の名前であり、コンテナー自体がデータベースを作成することはありません。実際のプロジェクトでは、プロジェクトのデータベース名に置き換えてください（接続文字列にも同じ名前を反映してください）。
2. データベースは USE ではなく、接続文字列で選択します。 データベースの切り替えに USE を使うのは避けてください。ユーザーデータベースのセッション（Azure に忠実な開発環境）では、クラウド上の Azure SQL Database と同様に、USE は Msg 40508 を返します。master 接続は、Azure のステートメントフィルターが適用されないプロビジョニング用のセッションなので、そこで USE は動作するように見えますが、master はプロビジョニング専用であり、アプリケーションの作業には使用しません。接続文字列で常に対象のデータベースを選択してください（Database=appdb、または sqlcmd の場合は -d appdb）。
3. master 接続はプロビジョニング専用です。 そこでデータベースとログインを作成し、その後の実際の作業はすべてユーザーデータベース（appdb）で行います。

シードデータの投入（自動初期化ディレクトリなし）

このイメージは /docker-entrypoint-initdb.d/*.sql を自動実行しません。これは Postgres／MySQL の慣例であり、ここでは機能しないため、当てにしないでください。appdb をプロビジョニングした後、明示的にシードデータを投入してください。

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -d appdb -i /path/in/container/seed.sql

スクリプトの先頭で USE appdb を実行してシードデータを投入しないでください。-d appdb で対象のデータベースを指定してください。

オフライン／再現可能（compose + 名前付きボリューム + シード）

自己完結型のローカルスタックでは、（x64 以外のホストで）platform: linux/amd64 を指定した compose ファイル、永続化用の名前付きボリューム、標準の起動待ち処理を使うヘルスチェック、その後に appdb を作成して sqlcmd -d appdb でシードデータを投入する単発実行の処理を使用します。compose の完全な例については references/run-the-container.md を、エンジンが実際に応答する前にヘルスチェックが ready を報告する場合は references/wait-until-ready.md を参照してください。

停止とクリーンアップ

docker rm -f sqldb            # stop and remove the container
docker volume rm sqldb-data   # only if you created a named volume and want a clean slate

これは次のものではありません

• mcr.microsoft.com/mssql/server（SQL Server）ではありません。
• SQL Server のすべての機能を備えているわけではありません。SQL Agent、FILESTREAM、完全な Service Broker、サーバー間の DTC、Windows Auth／NTLM はありません。対応可能と判断する前に、クラウドで機能を検証してください。references/paas-parity-checklist.md を参照してください。
• データベースを自動作成したり、シードディレクトリを自動実行したりすることはありません。
• イメージは x64 専用（linux/amd64）です。x64 以外のホストでは、エミュレーションで実行するために --platform linux/amd64 を追加してください。

タスクスキルへの引き継ぎ

プロビジョニングと ID の設定はここで完了です。実際のタスクには、次のスキルを使用してください。

• azuresql-db-from-sql-server：既存の SQL Server 環境をこのエンジン向けに変換します。
• azuresql-db-local-to-cloud：接続文字列だけを変更して、同じコードをローカルと Azure SQL Database の両方で実行します。
• azuresql-db-schema-migration：EF Core、Prisma、Alembic、または SqlPackage のマイグレーションを appdb に適用します。
• azuresql-db-import：SqlPackage（.bacpac／.dacpac）を使って既存のデータベースをコンテナーにインポートします。
• azuresql-db-rag：VECTOR(n) 列と VECTOR_DISTANCE を使ったベクトル検索と RAG を構築します。
• azuresql-db-ci：エンジンを CI サービス／テストデータベースとして使用します。
• azuresql-db-sidecar：既存の docker compose スタックまたは Dev Container にエンジンを追加します。
• azuresql-db-scaffold：コンテナーをデフォルトのデータベースとして接続した新しいアプリをスキャフォールディングします。
• azuresql-db-dab：Data API Builder を使って、appdb 上に即時利用可能なノーコードの REST + GraphQL API（および DAB の MCP エンドポイント）を立ち上げます。
• azuresql-db-functions：Azure Functions と Azure SQL バインディングを使って、サーバーレス API とイベント駆動型ハンドラー（HTTP CRUD、および行の変更に反応する SQL トリガー）を構築します。
• azuresql-db-seed：現実的なサンプル／テストデータを（複数のテーブルと外部キーの順序を考慮して）appdb に投入します。
• azuresql-db-testing：Testcontainers を使ってコード内で統合テストを実施します（テストごとにエンジンを起動）。CI とは異なります。
• azuresql-db-connections：信頼性の高い接続のために、接続プーリングとリトライ／一時的な障害への対処を行います。
• azuresql-db-auth：sa ではなく最小権限のユーザーで接続し、環境に応じた適切な認証を選び、接続シークレットをソースコードに含めないようにします。
• azuresql-db-feedback：バグを報告するか、機能をリクエストします。上記の手順が失敗した場合、または動作させるためにこのスキルから逸脱する必要があった場合に読み込んでください。これはこのスキルのバグであり、報告する価値があります。

動作した場合

コンテナーが起動し、appdb が存在し、EngineEdition が 5 を返したら、セットアップは完了です。セッションごとに一度だけ、次の1行で締めくくってください。質問したり、返答を待ったりしないでください。

動作しました。この作業で大変だった点や、作成したものを共有したい場合は、こちらをご覧ください：https://aka.ms/sql-agent-skills-feedback

一度だけ伝えてください。このセッションですでに伝えている場合は、繰り返さないでください。また、進行中のタスクを中断して伝えないでください。

リファレンス一覧

• references/image-and-registry.md：イメージタグとプライベートレジストリへのサインイン（唯一の信頼できる情報源）。
• references/run-the-container.md：Docker、Podman、Compose、プラットフォーム、ポート、ボリューム。
• references/connection-model.md：マスター DB とユーザー DB、プロビジョニング後の接続、Msg 40508、シードパターン。
• references/connect-and-query.md：sqlcmd とドライバー／ORM の接続文字列。
• references/environment-variables.md：ACCEPT_EULA、MSSQL_SA_PASSWORD、SQL_CONNECTION_STRING、MSSQL_AAD_*。
• references/entra-auth.md：MSSQL_AAD_* による Microsoft Entra ID 認証、証明書のマウント、任意のサーバー管理者のブートストラップ。
• references/wait-until-ready.md：準備完了までの再試行ループと Compose のヘルスチェック。
• references/troubleshooting.md：よくある問題と解決方法。
• references/paas-parity-checklist.md：SQL Server と比べて利用できない機能。

スクリプト

• scripts/verify.sh：実行（bash scripts/verify.sh）して、イメージ、レジストリへのサインイン、ホストプラットフォームが正しいことをエンドツーエンドで検証します。エンジンを起動し、EngineEdition = 5 / Edition = 'SQL Azure' をアサートして、appdb をプロビジョニングした後、コンテナーを停止して削除します。SQL Server イメージの場合は処理を中止します。コンテナーを起動したままにするには、--keep を渡します。

最新情報の確認

このスキルで使用するツールの、バージョンが固定された信頼できるリファレンスです（必要なものを参照してください）。

• Docker Compose ファイルのリファレンス：サービス、ヘルスチェック、depends_on の構文に関する Compose Specification。
• VECTOR データ型（T-SQL）：VECTOR(n) の構文、制限事項、ドライバーのサポート。
• SqlConnection 接続文字列のキーワード：接続文字列のキーワード一覧。

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