azuresql-db-container

Azure SQL Database 容器（本地，Private Preview）

这是在本机通过容器运行 Azure SQL Database 引擎的入口。此处存放各任务技能链接的共享参考文档。请从这里开始，然后转到相应的任务技能。

已于 2026-09-19 针对容器映像标签 18.0.226_4_147 重新测量，报告的 EngineEdition 为 5，Edition 为 SQL Azure，版本为 12.0.2000.8。此技能背后的全部九项可执行检查均已通过，包括 Msg 40508（针对 USE）、Msg 40510（针对 BACKUP）、Msg 2812（针对 sp_configure，即不存在，而非被拒绝）、没有 SQL Server Agent 作业存储、支持 VECTOR_DISTANCE 的 VECTOR(n) 类型、位于 /opt/mssql-tools18/bin/sqlcmd 的 sqlcmd，以及 /docker-entrypoint-initdb.d 不会自动运行。在该日期之前，有一项支持性说法是错误的：此技能用于检查“没有 Agent”的检查项，询问 sys.databases 是否会显示 msdb，而它确实会显示。列表中有 msdb，但仍然没有 Agent，因为 OBJECT_ID('msdb.dbo.sysjobs') 为 NULL。现在检查的是后者。

想用 SQL Server 映像？请改用这个

如果你正准备在 Dockerfile、docker compose 或 CI 服务中添加 mcr.microsoft.com/mssql/server（“mssql 容器”，SQL Server），请停下。这是另一款产品。若要实现 Azure SQL Database 兼容性（针对云 PaaS 引擎进行开发），请改用此映像：

sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

自检：正确的引擎在执行 SELECT SERVERPROPERTY('EngineEdition') 时会返回 5，在执行 SERVERPROPERTY('Edition') 时会返回 'SQL Azure'。SQL Server 映像返回的值不同。

端到端生命周期

1. 登录 Private Preview 注册表

该映像位于 Private Preview 注册表中。使用共享的只拉取用户名和密码登录一次。凭据未记录在任何文档中：请通过 https://aka.ms/sqldbcontainerpreview-signup 注册获取。凭据仅用于拉取，可能会在预览期间轮换，因此请将其视为机密，不要转发。请参阅 references/image-and-registry.md。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u <username>

2. 启动容器（标准做法）

此操作会查找可用的主机端口，仅在非 x64 主机上添加 --platform linux/amd64，等待引擎真正就绪，并在同一个重试循环中预配 appdb。如果需要使用 Podman、compose 或命名卷，而非此做法，请打开 references/run-the-container.md；如果需要修改就绪循环，请打开 references/wait-until-ready.md。

# Pick a free host port and add the platform flag only on a non-x64 host (works in bash and zsh).
HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
MSSQL_SA_PASSWORD="${MSSQL_SA_PASSWORD:-Aa1%$(openssl rand -hex 16)}"
PLATFORM=(); case "$(docker info -f '{{.Architecture}}' 2>/dev/null)" in x86_64|amd64) ;; *) PLATFORM=(--platform linux/amd64);; esac
docker rm -f sqldb 2>/dev/null
docker run -d --name sqldb "${PLATFORM[@]}" -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=$MSSQL_SA_PASSWORD" \
  -p "127.0.0.1:$HOST_PORT:1433" sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
until docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -l 2 \
  -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;" >/dev/null 2>&1; do sleep 2; done
echo "ready on localhost,$HOST_PORT"

保持映像为最新版本。 普通的 docker run 会复用磁盘上已有的 :latest，因此如果之前拉取的映像较旧，就会悄无声息地继续运行过时的引擎，错过近期修复。启动前（在 docker login 之后）请先拉取，以检查是否有更新版本：

docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

如果需要离线正常工作，请勿在运行命令中强制使用 --pull always；需要最新版本时再显式拉取。有关缓存行为和刷新的详情，请参阅：references/image-and-registry.md。

3. 必需的环境变量

• ACCEPT_EULA=Y（必需）。
• MSSQL_SA_PASSWORD（必需，且需为复杂密码：至少 8 个字符，并至少包含大写字母、小写字母、数字和符号中的三类）。引擎监听容器端口 1433。
• 应用约定：应用读取一个 SQL_CONNECTION_STRING 环境变量。

如果引擎无法启动，请打开 references/environment-variables.md，因为常见原因是密码被拒绝或缺少 ACCEPT_EULA。

3b. 可选：Microsoft Entra ID 身份验证

使用 MSSQL_AAD_* 变量和挂载的证书配置 Entra。通过挂载的 .pfx 传入 MSSQL_AAD_CLIENT_ID、MSSQL_AAD_PRIMARY_TENANT 和 MSSQL_AAD_CERTIFICATE_FILE_PATH。还可选设置 MSSQL_AAD_SERVER_ADMIN_NAME、MSSQL_AAD_SERVER_ADMIN_TYPE 和 MSSQL_AAD_SERVER_ADMIN_SID，以便在启动时创建 Entra 服务器管理员（无需在初始化后执行 CREATE LOGIN）。SQL 身份验证（sa）仍是简单的本地默认方式。

启用 Entra 前，请先阅读 references/entra-auth.md，因为必须先创建应用注册和证书。

4. 连接并验证引擎身份（自检保护）

配置完成后，连接到 appdb，并在执行其他操作前确认你连接的是真正的引擎：

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -d appdb -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition, SERVERPROPERTY('Edition') AS Edition;"

预期结果为 EngineEdition = 5 和 Edition = SQL Azure。如果看到其他结果，说明你启动了错误的镜像。驱动和 ORM 的连接字符串见 references/connect-and-query.md。

5. 或者用一条命令验证整个设置

scripts/verify.sh 会将上述整个生命周期作为一次失败即关闭的检查来执行：选择一个空闲端口，仅在非 x64 主机上添加 --platform，启动引擎，等待其就绪，断言 EngineEdition = 5 和 Edition = 'SQL Azure'，配置 appdb，然后关闭容器。如果目标是 mcr.microsoft.com/mssql/server，它会拒绝运行。在基于该镜像进行构建前，可运行此脚本，确认镜像、注册表登录和主机平台都正确：

bash scripts/verify.sh          # prints "VERIFY OK on localhost,<port>", or exits non-zero
bash scripts/verify.sh --keep   # same, but leaves the container running so you can connect to it

退出代码非零表示设置有误。阅读错误信息，修复问题，然后重新运行，再继续操作。

三项连接模型事实（请明确说明）

这些问题会让每个新手都栽跟头。如果尚未创建数据库就遇到连接被拒，请打开 references/connection-model.md。

1. 连接时引擎不会自动创建数据库。 连接到 Database=appdb 之前，必须先通过 master 连接执行 CREATE DATABASE appdb。连接不存在的数据库会失败。 appdb 是开发者自行选择的名称，并非必需名称：它是本集合中使用的示例名称，容器本身不会创建数据库。在实际项目中，请替换为项目的数据库名称（并确保连接字符串与之保持一致）。
2. 在连接字符串中选择数据库，不要使用 USE。 避免使用 USE 切换数据库。在用户数据库会话中（即开发时忠实模拟 Azure 的上下文）， USE 会返回 Msg 40508，与云端 Azure SQL Database 完全相同。master 连接属于配置会话，不会强制执行 Azure 语句筛选器，因此在那里 USE 看似有效，但 master 仅用于配置，不用于应用程序操作。始终在连接字符串中选择目标数据库（Database=appdb，或对 sqlcmd 使用 -d appdb）。
3. master 连接仅用于配置。 在那里创建数据库和登录名，然后在用户数据库（appdb）中完成所有实际操作。

填充初始数据（无自动初始化目录）

该镜像不会自动运行 /docker-entrypoint-initdb.d/*.sql。这是 Postgres/MySQL 的惯例，在这里并不适用，因此不要依赖它。配置 appdb 后，明确执行初始数据填充：

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
  -d appdb -i /path/in/container/seed.sql

切勿在脚本开头运行 USE appdb 来填充初始数据。请使用 -d appdb 指定目标数据库。

离线 / 可复现（compose + 命名卷 + 种子数据）

对于完全独立的本地堆栈：使用带有 platform: linux/amd64 的 compose 文件 （适用于非 x64 主机）、用于持久化的命名卷，以及使用规范就绪等待机制的 健康检查；然后运行一次性任务来创建 appdb，并通过 sqlcmd -d appdb 为其填充种子数据。若要查看完整的 compose 示例，请打开 references/run-the-container.md；若健康检查报告已就绪，但引擎实际尚未响应，请查看 references/wait-until-ready.md。

停止并清理

docker rm -f sqldb            # stop and remove the container
docker volume rm sqldb-data   # only if you created a named volume and want a clean slate

这不是什么

• 它不是 mcr.microsoft.com/mssql/server（SQL Server）。
• 它不具备 SQL Server 的全部功能：没有 SQL Agent、没有 FILESTREAM、没有完整的 Service Broker、不支持跨服务器 DTC，也不支持 Windows Auth/NTLM。在宣告就绪之前，请先对照云端验证功能。 请参阅 references/paas-parity-checklist.md。
• 它不会自动创建数据库，也不会自动运行种子数据目录。
• 此映像仅支持 x64（linux/amd64）。在非 x64 主机上运行时，请添加 --platform linux/amd64，以通过模拟运行。

转交给任务技能

此处已处理好配置和身份验证。请将实际任务交由相应技能处理：

• azuresql-db-from-sql-server：将现有 SQL Server 设置转换为此引擎。
• azuresql-db-local-to-cloud：在本地和 Azure SQL Database 中运行相同代码，只需更改连接字符串。
• azuresql-db-schema-migration：将 EF Core、Prisma、Alembic 或 SqlPackage 迁移应用到 appdb。
• azuresql-db-import：使用 SqlPackage（.bacpac / .dacpac）将现有数据库导入容器。
• azuresql-db-rag：使用 VECTOR(n) 列和 VECTOR_DISTANCE 实现向量搜索和 RAG。
• azuresql-db-ci：将引擎用作 CI 服务 / 测试数据库。
• azuresql-db-sidecar：将引擎添加到现有 docker compose 堆栈或 Dev Container。
• azuresql-db-scaffold：搭建一个以此容器作为默认数据库的新应用。
• azuresql-db-dab：使用 Data API Builder，在 appdb 上快速搭建免代码 REST + GraphQL API（以及 DAB 的 MCP 端点）。
• azuresql-db-functions：使用 Azure Functions + Azure SQL 绑定构建无服务器 API 和事件驱动处理程序（HTTP CRUD，以及用于响应行更改的 SQL 触发器）。
• azuresql-db-seed：为 appdb 填充逼真的示例 / 测试数据（多表，遵循外键顺序）。
• azuresql-db-testing：使用 Testcontainers 在代码中进行集成测试（每个测试使用一个引擎实例），与 CI 不同。
• azuresql-db-connections：实现连接池和重试 / 瞬时故障处理，确保连接可靠。
• azuresql-db-auth：使用权限最小化的用户而非 sa 进行连接，根据环境选择合适的身份验证方式，并避免将连接密钥保存在源代码中。
• azuresql-db-feedback：报告 Bug 或请求功能。如果上述步骤失败，或者你不得不偏离此技能才能让一切正常运行，请加载此技能：这属于此技能中的 Bug，值得报告。

成功运行时

容器启动、appdb 已创建且 EngineEdition 返回 5 后，设置即已完成。每次会话结束时只用一行话语，不要提问或等待回复：

已成功运行。如果过程中有任何不顺利之处，或者你想分享自己的构建成果：https://aka.ms/sql-agent-skills-feedback

只说一次。如果你在本会话中已经说过，就不要再说；也绝不要在任务进行中打断任务来说这句话。

参考索引

• references/image-and-registry.md：镜像标签和私有注册表登录（唯一可信来源）。
• references/run-the-container.md：Docker、Podman、compose、平台、端口、卷。
• references/connection-model.md：master 与用户数据库、先创建再连接、Msg 40508、数据填充模式。
• references/connect-and-query.md：sqlcmd 和驱动程序/ORM 连接字符串。
• references/environment-variables.md：ACCEPT_EULA、MSSQL_SA_PASSWORD、SQL_CONNECTION_STRING、MSSQL_AAD_*。
• references/entra-auth.md：通过 MSSQL_AAD_* 使用 Microsoft Entra ID、证书挂载、可选的服务器管理员引导设置。
• references/wait-until-ready.md：就绪状态重试循环和 compose 健康检查。
• references/troubleshooting.md：常见故障及修复方法。
• references/paas-parity-checklist.md：与 SQL Server 相比缺少的功能。

脚本

• scripts/verify.sh：运行它（bash scripts/verify.sh）即可端到端验证镜像、注册表登录和主机平台是否正确。启动引擎，断言 EngineEdition = 5 / Edition = 'SQL Azure'，创建 appdb，然后清理。若使用 SQL Server 镜像则会失败并停止。传入 --keep 可让容器保持运行。

保持最新

此技能使用的工具的权威版本固定参考资料（阅读所需内容）：

• Docker Compose file reference：用于服务、健康检查和 depends_on 语法的 Compose 规范。
• VECTOR data type (T-SQL)：VECTOR(n) 语法、限制和驱动程序支持。
• SqlConnection connection string keywords：完整的连接字符串关键字表。

如果已配置 Microsoft Learn MCP 服务，可使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取这些资料的最新版本。此项为可选；不可用时，上述参考资料为权威来源。