azuresql-db-sidecar

将 Azure SQL Database 容器用作 sidecar（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，build 为 12.0.2000.8。此技能背后的四项可执行检查均已通过：docker compose config 接受此技能生成的文件，包括平台覆盖、转义后的健康检查和两个 depends_on 条件；同一解析过程会拒绝虚构的条件名称，这项对照检查可防止第一项检查流于形式；引擎镜像内 /opt/mssql-tools18/bin/sqlcmd 可用；运行中的堆栈显示数据库容器先处于 Running 状态，之后才变为 healthy，且其健康日志以一次失败的检查开头。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 期间，注册表和标签均为临时配置。
• 注册表凭据：此镜像位于 Private Preview 专用注册表中。在运行 docker compose up 或构建 Dev Container 之前，先使用你注册 Private Preview 时获取的共享只拉取凭据登录：docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io。注册 Private Preview 的网址为 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 行为的上下文），USE 会返回 Msg 40508，与云端 Azure SQL Database 完全一致。master 连接属于预配会话，不会强制执行 Azure 语句筛选器，因此在那里 USE 看似有效；但 master 仅用于预配，不用于应用工作。始终在连接字符串中选择目标数据库（Database=appdb，或在 sqlcmd 中使用 -d appdb）。
• 应用连接字符串（单个 SQL_CONNECTION_STRING 环境变量，主机使用服务名）： 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 中。不要删除或重命名现有服务；只需添加 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

初始化数据（可选）

该映像不会自动运行初始化 SQL。若要初始化数据，请取消注释 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

开发容器

使用 Docker Compose 作为开发容器后端，以便沿用相同的 sqldb + sqldb-init 服务。在 .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 技能并提出提交报告。
• 当所有上述规则都通过且任务完成后，每个会话只需以一行结束，不要提问或等待回复：“That worked. If anything about this was rough, or you want to share what you built: 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 规范。
• devcontainer.json 参考：开发容器元数据键（dockerComposeFile、service、runServices、remoteEnv）。

如果已配置 Microsoft Learn MCP 服务，请使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取这些资料的当前版本。此步骤为可选；若无法使用，上述参考资料即为权威资料。