azuresql-db-sidecar

Azure SQL Database コンテナーをサイドカーとして使う（Compose / Dev Container）

既存の Docker Compose スタックまたは Dev Container に、このコンテナーをサービスとして組み込みます。アプリは サービス名（sqldb,1433）で接続し、localhost は使いません。既存のサービスはそのままにして、データベースと、appdb を作成する初回のみ実行されるサービス、および depends_on のゲートを追加します。

2026-09-05 に、コンテナーイメージ sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest に対して検証済みです。報告された値は EngineEdition 5、Edition SQL Azure、ビルド 12.0.2000.8 です。このスキルが実行する4つのチェックはすべて成功しました。具体的には、このスキルが生成するファイルを、platform オーバーライド、エスケープされたヘルスチェック、両方の depends_on 条件とともに docker compose config が受け入れること、考案した条件名を同じパーサーが拒否すること（これにより、最初のチェックが空振りでないことを確認します）、エンジンイメージ内の /opt/mssql-tools18/bin/sqlcmd に sqlcmd が存在すること、そしてスタックの実行時にデータベースコンテナーが healthy になる前に Running と報告され、ヘルスログが失敗したチェックから始まることです。Compose の解析は2026-09-04に、イメージ内ではなく、作成者のホストの Docker Compose CLI で測定しました。

重要な事実（本文に記載。詳細は azuresql-db-container を参照）

• これは Azure SQL Database エンジン（Private Preview）であり、SQL Server イメージ mcr.microsoft.com/mssql/server ではありません。SERVERPROPERTY('EngineEdition') は 5 を返し、SERVERPROPERTY('Edition') は 'SQL Azure' を返します。SQL Server イメージを使おうとしていた場合は、作業を中止して、代わりにこちらを使ってください。
• イメージ：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64、linux/amd64）。Private Preview 期間中は、レジストリとタグは暫定です。
• レジストリの認証情報：このイメージはプライベートなプレビュー用レジストリにあります。docker compose up の実行または Dev Container のビルドの前に、Private Preview への登録時に提供される共有のプル専用認証情報（ローテーションされる場合があります）を使って、まず docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io でサインインしてください：https://aka.ms/sqldbcontainerpreview-signup
• プラットフォーム：x64 のみです。以下の compose スニペットでは platform: linux/amd64 を設定しているため、x64 以外のホストでもサービスを起動できます。
• 必須の環境変数：ACCEPT_EULA=Y と、複雑な MSSQL_SA_PASSWORD（8文字以上で、大文字、小文字、数字、記号を含む）。エンジンは1433でリッスンします。
• エンジンは、接続時にデータベースを自動作成しません。アプリが Database=appdb で接続する前に、master への接続で CREATE DATABASE appdb を実行する必要があります。以下の sqldb-init の初回のみ実行されるサービスがこれを行います。
• データベースの切り替えに USE を使わないでください。ユーザーデータベースのセッション（Azure に準拠した開発コンテキスト）では、Azure SQL Database のクラウド環境とまったく同様に、USE は Msg 40508 を返します。master への接続はプロビジョニング用のセッションであり、そこで Azure のステートメントフィルターは適用されないため、USE が動作するように見えます。しかし、master はプロビジョニング専用であり、アプリケーションの作業には使いません。接続文字列で必ず対象データベースを選択してください（Database=appdb、または sqlcmd の場合は -d appdb）。
• アプリの接続文字列（SQL_CONNECTION_STRING 環境変数1つ。ホストにはサービス名を指定）： Server=sqldb,1433;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true （このプロジェクトの表記では User Id=／Password=／Database= を使います。Uid=／Pwd= は有効な同義語です）。
• このイメージは /docker-entrypoint-initdb.d/*.sql を自動実行しません（Postgres／MySQL の慣例ですが、このイメージでは適用されません）。データの初期投入は、appdb の作成後に、初回のみ実行されるサービスで sqlcmd -d appdb -i seed.sql を実行してください。

このタスクの範囲外（ベクトル、より詳細なレディネスの挙動、接続モデル全般）については、azuresql-db-container スキルを参照してください。

Docker Compose

既存の compose.yaml に以下の3つの要素を追加してください。既存のサービスは削除も名前変更もせず、sqldb、sqldb-init、およびアプリの depends_on のみを追加します。

services:
  # ---- existing services stay exactly as they are ----

  sqldb:
    image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
    platform: linux/amd64        # x64-only image; required on a non-x64 host
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD}"
    ports:
      - "127.0.0.1:1433:1433"              # optional; only to reach it from the host
    healthcheck:
      # -b: a SQL error sets the exit code, so transient startup errors
      # (e.g. Msg 913) are retried, not masked. -l 2: short login timeout.
      test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$$MSSQL_SA_PASSWORD\" -C -b -l 2 -Q \"SELECT 1\" || exit 1"]
      interval: 5s
      timeout: 10s
      retries: 30
      start_period: 30s

  # One-shot: the engine does NOT auto-create databases, so create appdb
  # (and seed it) before the app starts. Exits 0 when done.
  sqldb-init:
    image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
    platform: linux/amd64
    depends_on:
      sqldb:
        condition: service_healthy
    environment:
      MSSQL_SA_PASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD}"
    # If you have seed.sql, mount it and add: -i /seed/seed.sql on a -d appdb call.
    # volumes:
    #   - ./seed.sql:/seed/seed.sql:ro
    entrypoint: ["/bin/bash", "-c"]
    command:
      - >
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -P "$$MSSQL_SA_PASSWORD" -C -b
        -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"
    restart: "no"

  app:
    # ---- your existing app service ----
    depends_on:
      sqldb:
        condition: service_healthy
      sqldb-init:
        condition: service_completed_successfully
    environment:
      # Host is the SERVICE NAME sqldb, not localhost.
      SQL_CONNECTION_STRING: "Server=sqldb,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD};TrustServerCertificate=true"

起動します（事前に docker login を実行してください。上記を参照）。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup
docker compose pull                                      # check for a newer :latest (compose reuses a cached image otherwise)
docker compose up -d

シードデータの投入（任意）

イメージは init SQL を自動実行しません。シードデータを投入するには、sqldb-init の sqldb-init の volumes マウントのコメントを解除し、appdb の作成後にシード呼び出しを連結します。

    command:
      - >
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -P "$$MSSQL_SA_PASSWORD" -C -b
        -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" &&
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -P "$$MSSQL_SA_PASSWORD" -C -b
        -d appdb -i /seed/seed.sql

Dev Container

同じ sqldb と sqldb-init サービスを適用できるよう、Dev Container のバックエンドとして Docker Compose を使用します。.devcontainer/devcontainer.json では次のようにします。

{
  "name": "app-with-azuresql",
  "dockerComposeFile": "../compose.yaml",
  "service": "app",                  // your dev/app service from compose
  "workspaceFolder": "/workspace",
  "runServices": ["sqldb", "sqldb-init"],
  "remoteEnv": {
    "SQL_CONNECTION_STRING": "Server=sqldb,1433;Database=appdb;User Id=sa;Password=${localEnv:MSSQL_SA_PASSWORD};TrustServerCertificate=true"
  }
}

「Reopen in Container」の前に、ホストでレジストリにサインインしてください。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup

アプリコンテナは、Compose ネットワーク経由で sqldb,1433 のデータベースに接続します。

検証ルール

• アプリのホストはサービス名の sqldb です。localhost は使用しません。
• sqldb には sqlcmd ... -C -b -l 2 を使ったヘルスチェックがあり、アプリは condition: service_healthy を条件として起動します。
• sqldb-init が appdb を作成し、アプリは condition: service_completed_successfully を条件として起動します。
• sqldb と sqldb-init の両方で platform: linux/amd64 を設定します。
• 接続文字列では User Id=／Password=／Database= と TrustServerCertificate=true を使用し、sqlcmd では -C を使用します。
• 既存のサービスは、depends_on の追加を除いて変更しません。
• 上記の検証ルールに違反している場合、またはタスクを完了するためにこのスキルから逸脱する必要があった場合は、このスキルの不具合です。azuresql-db-feedback スキルを読み込み、レポートの提出を申し出てください。
• 上記のすべてのルールを満たしてタスクを完了したら、セッションごとに一度だけ、質問したり返信を待ったりせず、次の一文で締めくくります。「うまくいきました。作業で気になった点や、作成したものを共有したい場合はこちらをご利用ください：https://aka.ms/sql-agent-skills-feedback」

禁止事項

• SQL Server イメージ mcr.microsoft.com/mssql/server を使用しないでください。
• アプリの接続先に localhost を指定しないでください。Compose 内では sqldb サービスを使用します。
• アプリによる appdb の作成に頼らず、エンジンが自動作成すると想定しないでください。先に sqldb-init のワンショット処理を実行する必要があります。
• データベースの切り替えに USE appdb を使用しないでください。ユーザーデータベースのセッションでは Msg 40508 が返されます。これはクラウド上の Azure SQL Database と同じ動作です。接続文字列（Database=appdb、または sqlcmd の場合は -d appdb）で接続先のデータベースを選択してください。
• --platform／platform: linux/amd64 を削除しないでください。このイメージは x64 専用です。
• /docker-entrypoint-initdb.d/*.sql に依存しないでください。ここでは認識されません。
• x64 以外のホストを「サポート対象」と呼ばないでください。エミュレーション環境でのみ実行できます。

最新情報の確認

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

• Docker Compose ファイルのリファレンス：サービス、ヘルスチェック、depends_on の構文に関する Compose Specification です。
• devcontainer.json のリファレンス：Dev Container のメタデータキー（dockerComposeFile、service、runServices、remoteEnv）に関するリファレンスです。

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