azuresql-db-sidecar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

The Azure SQL Database container as a sidecar (Compose / Dev Container)

将 Azure SQL Database 容器作为 sidecar 使用(Compose / Dev Container)

Wire the container into an existing Docker Compose stack or Dev Container as a service the app reaches by service name (
sqldb,1433
), never
localhost
. Keep existing services intact; add the database, an init one-shot that creates
appdb
, and a
depends_on
gate.
将该容器接入现有 Docker Compose 技术栈或 Dev Container,作为一个供应用通过服务名称(
sqldb,1433
)访问的服务,绝不能使用
localhost
。保持现有服务不变;添加数据库、用于创建
appdb
的一次性 init 任务,以及一道
depends_on
门控。

Load-bearing facts (inlined; full detail in azuresql-db-container)

关键事实(内联;完整详情见 azuresql-db-container)

  • This is the Azure SQL Database engine (Private Preview), not the SQL Server image
    mcr.microsoft.com/mssql/server
    .
    SERVERPROPERTY('EngineEdition')
    returns
    5
    ,
    SERVERPROPERTY('Edition')
    returns
    'SQL Azure'
    , and the build reports as
    12.0.2000.8
    . If you were about to use the SQL Server image, stop and use this instead.
  • Image:
    sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
    (x64,
    linux/amd64
    ). Registry and tag are provisional during Private Preview.
  • Registry credentials: the image lives in a private preview registry. Sign in first with
    docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io
    using the shared pull-only credentials provided when you sign up for the Private Preview at https://aka.ms/sqldbcontainerpreview-signup (they may rotate) before
    docker compose up
    or building the Dev Container.
  • Platform: x64 only. The compose snippets below set
    platform: linux/amd64
    so the service starts on a non-x64 host.
  • Required env:
    ACCEPT_EULA=Y
    and a complex
    MSSQL_SA_PASSWORD
    (8+ chars, upper/lower/digit/symbol). Engine listens on 1433.
  • The engine does NOT auto-create databases on connect. You must
    CREATE DATABASE appdb
    on a master connection before the app connects with
    Database=appdb
    . That is what the
    sqldb-init
    one-shot below does.
  • Avoid
    USE
    to switch databases. In a user-database session (the Azure-faithful context where you develop),
    USE
    returns
    Msg 40508
    , exactly as in Azure SQL Database in the cloud. A
    master
    connection is a provisioning session where the Azure statement filter is not enforced, so
    USE
    appears to work there, but
    master
    is for provisioning only, not application work. Always select the target database in the connection string (
    Database=appdb
    , or
    -d appdb
    for sqlcmd).
  • App connection string (single
    SQL_CONNECTION_STRING
    env var, service name host):
    Server=sqldb,1433;Database=appdb;User Id=sa;Password=<sa-password>;TrustServerCertificate=true
    (
    <sa-password>
    is
    MSSQL_SA_PASSWORD
    ; the compose and Dev Container files below interpolate it) (house style spells it
    User Id=
    /
    Password=
    /
    Database=
    ;
    Uid=
    /
    Pwd=
    are valid synonyms).
  • The image does NOT auto-run
    /docker-entrypoint-initdb.d/*.sql
    (a Postgres/MySQL convention, not honored here). Seed in the init one-shot with
    sqlcmd -d appdb -i seed.sql
    AFTER
    appdb
    exists.
For anything beyond this task (vectors, deeper readiness behavior, full connection model), see the azuresql-db-container skill.
  • 这是 Azure SQL Database 引擎(Private Preview),而不是 SQL Server 镜像
    mcr.microsoft.com/mssql/server
    。
    SERVERPROPERTY('EngineEdition')
    返回
    5
    ,
    SERVERPROPERTY('Edition')
    返回
    'SQL Azure'
    ,构建版本报告为
    12.0.2000.8
    。如果你正准备使用 SQL Server 镜像,请停下并改用此镜像。
  • 镜像:
    sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
    (x64,
    linux/amd64
    )。在 Private Preview 期间,Registry 和 tag 均为暂定值。
  • Registry 凭据:镜像位于私有预览 Registry 中。执行
    docker compose up
    或构建 Dev Container 之前,先使用
    docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io
    登录,并使用报名 Private Preview 时提供的共享仅拉取凭据(这些凭据可能会轮换)。
  • 平台:仅支持 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=<sa-password>;TrustServerCertificate=true
    (
    <sa-password>
    即
    MSSQL_SA_PASSWORD
    ;下方的 compose 和 Dev Container 文件会对其进行插值) (内部约定写作
    User Id=
    /
    Password=
    /
    Database=
    ;
    Uid=
    /
    Pwd=
    也是有效的同义词)。
  • 该镜像不会自动运行
    /docker-entrypoint-initdb.d/*.sql
    (这是 Postgres/MySQL 的约定,此处不支持)。在
    appdb
    已存在后,通过 init 一次性任务使用
    sqlcmd -d appdb -i seed.sql
    写入种子数据。
超出本任务范围的内容(向量、更深入的就绪行为、完整连接模型),请参阅 azuresql-db-container skill。

Docker Compose

Docker Compose

Add these three pieces to your existing
compose.yaml
. Do not remove or rename existing services; just add
sqldb
,
sqldb-init
, and a
depends_on
on the app.
yaml
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 before running Docker Compose}"
      SQLCMDPASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD before running Docker Compose}"
    ports:
      - "127.0.0.1:1433:1433"    # optional; only to reach it from this 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 -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:
      SQLCMDPASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD before running Docker Compose}"
    # 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 -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"
Bring it up (after
docker login
, see above):
bash
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup
docker compose pull                                      # refresh the daily-rebuilt :latest (compose reuses a cached image otherwise)
docker compose up -d
docker compose config
accepts this file, including the platform override, the escaped health check and both
depends_on
conditions, and rejects an unknown condition name. The engine image ships
sqlcmd
at
/opt/mssql-tools18/bin/sqlcmd
, which the health check and the init one-shot call. After
up
, the database container shows as
Running
before it is
healthy
, and its health log begins with a failed check.
将以下三部分添加到现有
compose.yaml
中。不要移除或重命名现有服务;只需添加
sqldb
、
sqldb-init
,并在 app 上添加
depends_on
。
yaml
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 before running Docker Compose}"
      SQLCMDPASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD before running Docker Compose}"
    ports:
      - "127.0.0.1:1433:1433"    # optional; only to reach it from this 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 -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:
      SQLCMDPASSWORD: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD before running Docker Compose}"
    # 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 -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
,见上文):
bash
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup
docker compose pull                                      # refresh the daily-rebuilt :latest (compose reuses a cached image otherwise)
docker compose up -d
docker compose config
可以接受此文件,包括
platform
覆盖、转义后的健康检查以及两种
depends_on
条件,并会拒绝未知的条件名称。引擎镜像在
/opt/mssql-tools18/bin/sqlcmd
路径中自带
sqlcmd
,健康检查和 init 一次性任务都会调用它。执行
up
后,数据库容器在达到
healthy
状态之前会显示为
Running
;其健康检查日志会以一次失败的检查开头。

Seeding (optional)

数据初始化(可选)

The image does not auto-run init SQL. To seed, uncomment the
volumes
mount in
sqldb-init
and chain a seed call AFTER
appdb
is created:
yaml
    command:
      - >
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -C -b
        -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" &&
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -C -b
        -d appdb -i /seed/seed.sql
该镜像不会自动运行初始化 SQL。要进行数据初始化,请取消
sqldb-init
中
volumes
挂载的注释,并在
appdb
创建之后链式调用 seed 命令:
yaml
    command:
      - >
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -C -b
        -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" &&
        /opt/mssql-tools18/bin/sqlcmd -S sqldb -U sa -C -b
        -d appdb -i /seed/seed.sql

Dev Container

Dev Container

Use Docker Compose as the Dev Container backend so the same
sqldb
+
sqldb-init
services apply. In
.devcontainer/devcontainer.json
:
jsonc
{
  "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"
  }
}
Sign in to the registry on the host before "Reopen in Container":
bash
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup
The app container reaches the database at
sqldb,1433
over the compose network.
使用 Docker Compose 作为 Dev Container 后端,以便沿用同一组
sqldb
+
sqldb-init
服务。在
.devcontainer/devcontainer.json
中:
jsonc
{
  "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”之前,先在主机上登录 Registry:
bash
docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup
应用容器通过 compose 网络在
sqldb,1433
处访问数据库。

Validation rules

验证规则

  • App host is
    sqldb
    (service name), never
    localhost
    .
  • sqldb
    has a healthcheck using
    sqlcmd ... -C -b -l 2
    ; the app gates on
    condition: service_healthy
    .
  • sqldb-init
    creates
    appdb
    and is gated by the app via
    condition: service_completed_successfully
    .
  • Both
    sqldb
    and
    sqldb-init
    set
    platform: linux/amd64
    .
  • Connection string uses
    User Id=
    /
    Password=
    /
    Database=
    and
    TrustServerCertificate=true
    ; sqlcmd uses
    -C
    .
  • Existing services are unchanged except for added
    depends_on
    .
  • If a validation rule above fails, or you had to deviate from this skill to make the task work, that is a bug in this skill: load the azuresql-db-feedback skill and offer to file a report.
  • When every rule above passes and the task is done, close with ONE line, once per session, and do not ask a question or wait for a reply: "That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"
  • 应用主机为
    sqldb
    (服务名称),绝不能是
    localhost
    。
  • sqldb
    使用
    sqlcmd ... -C -b -l 2
    的 healthcheck;应用通过
    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
    外,现有服务保持不变。
  • 如果上述任一验证规则失败,或者你必须偏离此 skill 才能让任务正常运行,那么这就是此 skill 中的 bug:加载 azuresql-db-feedback skill,并提供提交报告的选项。
  • 当上述每条规则均通过且任务完成时,每个会话仅以下面这一行结束一次,不要提问或等待回复:"That worked. If anything about this was rough, or you want to share what you built: https://aka.ms/sql-agent-skills-feedback"

Check it worked

检查是否成功

  • Positive verification: Start the application and sidecar, require one successful database round trip, and verify the sidecar uses the declared endpoint.
  • Cleanup verification: Stop and remove both services, their owned network, and temporary configuration files.
  • Report success only after both observations pass.
  • 正向验证: 启动应用和 sidecar,要求完成至少一次成功的数据库往返通信,并验证 sidecar 使用声明的 endpoint。
  • 清理验证: 停止并移除两个服务、它们所属的网络以及临时配置文件。
  • 仅在两项观察均通过后报告成功。

Do not

禁止事项

  • Do not use the SQL Server image
    mcr.microsoft.com/mssql/server
    .
  • Do not point the app at
    localhost
    ; inside compose it is the
    sqldb
    service.
  • Do not rely on the app to create
    appdb
    , and do not assume the engine auto-creates it; the
    sqldb-init
    one-shot must run first.
  • Do not use
    USE appdb
    to switch databases; a user-database session returns
    Msg 40508
    , exactly as in Azure SQL Database in the cloud. Select the target database in the connection string (
    Database=appdb
    , or
    -d appdb
    for sqlcmd).
  • Do not drop
    --platform
    /
    platform: linux/amd64
    ; the image is x64 only.
  • Do not depend on
    /docker-entrypoint-initdb.d/*.sql
    ; it is not honored here.
  • Do not call a non-x64 host "supported"; it runs under emulation only.
  • 不要使用 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 主机称为“受支持”;它仅在模拟模式下运行。

Staying current

保持最新

Authoritative, version-pinned references for the tools this skill uses (read the one you need):
If the Microsoft Learn MCP server is configured, use
mcp__microsoft-learn__microsoft_docs_search
or
mcp__microsoft-learn__microsoft_docs_fetch
to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative.
本 skill 所用工具的权威、版本锁定参考资料(按需阅读):
如果已配置 Microsoft Learn MCP server,请使用
mcp__microsoft-learn__microsoft_docs_search
或
mcp__microsoft-learn__microsoft_docs_fetch
按需获取上述内容的当前版本。该步骤为可选;如果 server 不可用,以上参考资料即为权威来源。