Adds the Azure SQL Database container as a sidecar service in an existing Docker Compose stack or Dev Container. Use when wiring the local Azure SQL Database engine into compose or devcontainer.json, when an app needs a SQL backend via a service name (not localhost), or for prompts like "add SQL to my compose", "add a database service", "depends_on database", "devcontainer SQL sidecar", "compose healthcheck for SQL", "wait for the database before starting the app". Handles platform linux/amd64, the private registry login, the healthcheck wait-until-ready, and a one-shot init service that creates appdb (the engine does not auto-create databases). Not the SQL Server image. Prefer this for any compose or Dev Container SQL wiring.
Adds the Azure SQL Database container as a sidecar service in an existing Docker Compose stack or Dev Container. Use when wiring the local Azure SQL Database engine into compose or devcontainer.json, when an app needs a SQL backend via a service name (not localhost), or for prompts like "add SQL to my compose", "add a database service", "depends_on database", "devcontainer SQL sidecar", "compose healthcheck for SQL", "wait for the database before starting the app". Handles platform linux/amd64, the private registry login, the healthcheck wait-until-ready, and a one-shot init service that creates appdb (the engine does not auto-create databases). Not the SQL Server image. Prefer this for any compose or Dev Container SQL wiring.
The Azure SQL Database container as a 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.
Load-bearing facts (inlined; full detail in 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'. 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 (they may rotate) before
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
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=YourStr0ng_Passw0rd;TrustServerCertificate=true
(use User Id=/Password=/Database=, not Uid=/Pwd=).
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.
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.
services:# ---- existing services stay exactly as they are ----sqldb:image:sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latestplatform:linux/amd64# x64-only image; required on a non-x64 hostenvironment:ACCEPT_EULA:"Y"MSSQL_SA_PASSWORD:"YourStr0ng_Passw0rd"ports:-"1433:1433"# optional; only to reach it from the hosthealthcheck:# -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:5stimeout:10sretries:30start_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:latestplatform:linux/amd64depends_on:sqldb:condition:service_healthyenvironment:MSSQL_SA_PASSWORD:"YourStr0ng_Passw0rd"# If you have seed.sql, mount it and add: -i /seed/seed.sql on a -d appdb call.# volumes:# - ./seed.sql:/seed/seed.sql:roentrypoint: ["/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_healthysqldb-init:condition:service_completed_successfullyenvironment:# Host is the SERVICE NAME sqldb, not localhost.SQL_CONNECTION_STRING:"Server=sqldb,1433;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true"
Bring it up (after docker login, see above):
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
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:
Use Docker Compose as the Dev Container backend so the same sqldb +
sqldb-init services apply. In .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=YourStr0ng_Passw0rd;TrustServerCertificate=true"}}
Sign in to the registry on the host before "Reopen in Container":
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.
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"
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. 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).
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.
Staying current
Authoritative, version-pinned references for the tools this skill uses (read the one you need):
devcontainer.json reference: the Dev Container metadata keys (dockerComposeFile, service, runServices, remoteEnv).
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.
