azuresql-db-sidecar
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThe 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 (),
never . Keep existing services intact; add the database, an init
one-shot that creates , and a gate.
sqldb,1433localhostappdbdepends_on将该容器接入现有 Docker Compose 技术栈或 Dev Container,作为一个供应用通过服务名称()访问的服务,绝不能使用 。保持现有服务不变;添加数据库、用于创建 的一次性 init 任务,以及一道 门控。
sqldb,1433localhostappdbdepends_onLoad-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/serverreturnsSERVERPROPERTY('EngineEdition'),5returnsSERVERPROPERTY('Edition'), and the build reports as'SQL Azure'. If you were about to use the SQL Server image, stop and use this instead.12.0.2000.8 - Image: (x64,
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest). Registry and tag are provisional during Private Preview.linux/amd64 - Registry credentials: the image lives in a private preview registry. Sign in
first with 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 login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.ioor building the Dev Container.docker compose up - Platform: x64 only. The compose snippets below set
so the service starts on a non-x64 host.
platform: linux/amd64 - Required env: and a complex
ACCEPT_EULA=Y(8+ chars, upper/lower/digit/symbol). Engine listens on 1433.MSSQL_SA_PASSWORD - The engine does NOT auto-create databases on connect. You must
on a master connection before the app connects with
CREATE DATABASE appdb. That is what theDatabase=appdbone-shot below does.sqldb-init - Avoid to switch databases. In a user-database session (the Azure-faithful context where you develop),
USEreturnsUSE, exactly as in Azure SQL Database in the cloud. AMsg 40508connection is a provisioning session where the Azure statement filter is not enforced, somasterappears to work there, butUSEis for provisioning only, not application work. Always select the target database in the connection string (master, orDatabase=appdbfor sqlcmd).-d appdb - App connection string (single env var, service name host):
SQL_CONNECTION_STRING(Server=sqldb,1433;Database=appdb;User Id=sa;Password=<sa-password>;TrustServerCertificate=trueis<sa-password>; the compose and Dev Container files below interpolate it) (house style spells itMSSQL_SA_PASSWORD/User Id=/Password=;Database=/Uid=are valid synonyms).Pwd= - The image does NOT auto-run (a Postgres/MySQL convention, not honored here). Seed in the init one-shot with
/docker-entrypoint-initdb.d/*.sqlAFTERsqlcmd -d appdb -i seed.sqlexists.appdb
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'。如果你正准备使用 SQL Server 镜像,请停下并改用此镜像。12.0.2000.8 - 镜像:(x64,
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest)。在 Private Preview 期间,Registry 和 tag 均为暂定值。linux/amd64 - Registry 凭据:镜像位于私有预览 Registry 中。执行 或构建 Dev Container 之前,先使用
docker compose up登录,并使用报名 Private Preview 时提供的共享仅拉取凭据(这些凭据可能会轮换)。docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io - 平台:仅支持 x64。下方 compose 代码片段设置了 ,以便服务在非 x64 主机上启动。
platform: linux/amd64 - 必需环境变量:和复杂的
ACCEPT_EULA=Y(至少 8 个字符,包含大写字母、小写字母、数字和符号)。引擎监听 1433 端口。MSSQL_SA_PASSWORD - 引擎在连接时不会自动创建数据库。应用使用 连接之前,必须通过 master 连接执行
Database=appdb。下方的CREATE DATABASE appdb一次性任务正是为此而设。sqldb-init - 避免使用 切换数据库。在用户数据库会话(开发时与 Azure 行为保持一致的环境)中,
USE会返回USE,与云端 Azure SQL Database 中的行为完全相同。Msg 40508连接是预配会话,其中不强制执行 Azure 语句过滤器,因此master看起来可以正常工作;但USE仅用于预配,不用于应用工作。始终在连接字符串中选择目标数据库(master,或对 sqlcmd 使用Database=appdb)。-d appdb - 应用连接字符串(使用单个 环境变量,主机采用服务名称):
SQL_CONNECTION_STRING(Server=sqldb,1433;Database=appdb;User Id=sa;Password=<sa-password>;TrustServerCertificate=true即<sa-password>;下方的 compose 和 Dev Container 文件会对其进行插值) (内部约定写作MSSQL_SA_PASSWORD/User Id=/Password=;Database=/Uid=也是有效的同义词)。Pwd= - 该镜像不会自动运行 (这是 Postgres/MySQL 的约定,此处不支持)。在
/docker-entrypoint-initdb.d/*.sql已存在后,通过 init 一次性任务使用appdb写入种子数据。sqlcmd -d appdb -i seed.sql
超出本任务范围的内容(向量、更深入的就绪行为、完整连接模型),请参阅 azuresql-db-container skill。
Docker Compose
Docker Compose
Add these three pieces to your existing . Do not remove or rename
existing services; just add , , and a on the app.
compose.yamlsqldbsqldb-initdepends_onyaml
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 , see above):
docker loginbash
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 -ddocker compose configdepends_onsqlcmd/opt/mssql-tools18/bin/sqlcmdupRunninghealthy将以下三部分添加到现有 中。不要移除或重命名现有服务;只需添加 、,并在 app 上添加 。
compose.yamlsqldbsqldb-initdepends_onyaml
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 loginbash
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 -ddocker compose configplatformdepends_on/opt/mssql-tools18/bin/sqlcmdsqlcmduphealthyRunningSeeding (optional)
数据初始化(可选)
The image does not auto-run init SQL. To seed, uncomment the mount in
and chain a seed call AFTER is created:
volumessqldb-initappdbyaml
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。要进行数据初始化,请取消 中 挂载的注释,并在 创建之后链式调用 seed 命令:
sqldb-initvolumesappdbyaml
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.sqlDev Container
Dev Container
Use Docker Compose as the Dev Container backend so the same +
services apply. In :
sqldbsqldb-init.devcontainer/devcontainer.jsonjsonc
{
"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-signupThe app container reaches the database at over the compose network.
sqldb,1433使用 Docker Compose 作为 Dev Container 后端,以便沿用同一组 + 服务。在 中:
sqldbsqldb-init.devcontainer/devcontainer.jsonjsonc
{
"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,1433Validation rules
验证规则
- App host is (service name), never
sqldb.localhost - has a healthcheck using
sqldb; the app gates onsqlcmd ... -C -b -l 2.condition: service_healthy - creates
sqldb-initand is gated by the app viaappdb.condition: service_completed_successfully - Both and
sqldbsetsqldb-init.platform: linux/amd64 - Connection string uses /
User Id=/Password=andDatabase=; sqlcmd usesTrustServerCertificate=true.-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的 healthcheck;应用通过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=;sqlcmd 使用TrustServerCertificate=true。-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 ; inside compose it is the
localhostservice.sqldb - Do not rely on the app to create , and do not assume the engine auto-creates it; the
appdbone-shot must run first.sqldb-init - Do not use to switch databases; a user-database session returns
USE appdb, exactly as in Azure SQL Database in the cloud. Select the target database in the connection string (Msg 40508, orDatabase=appdbfor sqlcmd).-d appdb - Do not drop /
--platform; the image is x64 only.platform: linux/amd64 - Do not depend on ; it is not honored here.
/docker-entrypoint-initdb.d/*.sql - Do not call a non-x64 host "supported"; it runs under emulation only.
- 不要使用 SQL Server 镜像 。
mcr.microsoft.com/mssql/server - 不要将应用指向 ;在 compose 内部应使用
localhost服务。sqldb - 不要依赖应用创建 ,也不要假设引擎会自动创建;
appdb一次性任务必须先运行。sqldb-init - 不要使用 切换数据库;在用户数据库会话中会返回
USE appdb,与云端 Azure SQL Database 完全一致。请在连接字符串中选择目标数据库(Msg 40508,或对 sqlcmd 使用Database=appdb)。-d appdb - 不要移除 /
--platform;该镜像仅支持 x64。platform: linux/amd64 - 不要依赖 ;此处不支持这种机制。
/docker-entrypoint-initdb.d/*.sql - 不要将非 x64 主机称为“受支持”;它仅在模拟模式下运行。
Staying current
保持最新
Authoritative, version-pinned references for the tools this skill uses (read the one you need):
- Docker Compose file reference: the Compose Specification for service, healthcheck, and depends_on syntax.
- devcontainer.json reference: the Dev Container metadata keys (dockerComposeFile, service, runServices, remoteEnv).
If the Microsoft Learn MCP server is configured, use or to fetch the current version of any of these on demand. It is optional; when it is unavailable, the references above are authoritative.
mcp__microsoft-learn__microsoft_docs_searchmcp__microsoft-learn__microsoft_docs_fetch本 skill 所用工具的权威、版本锁定参考资料(按需阅读):
- Docker Compose 文件参考:有关 service、healthcheck 和 depends_on 语法的 Compose Specification。
- devcontainer.json 参考:Dev Container 元数据键(dockerComposeFile、service、runServices、remoteEnv)。
如果已配置 Microsoft Learn MCP server,请使用 或 按需获取上述内容的当前版本。该步骤为可选;如果 server 不可用,以上参考资料即为权威来源。
mcp__microsoft-learn__microsoft_docs_searchmcp__microsoft-learn__microsoft_docs_fetch