azuresql-db-testing

使用 Testcontainers 对 Azure SQL Database 容器运行集成测试

编写集成测试，以便通过代码启动一个真实的 Azure SQL Database 容器（Private Preview）， 创建 appdb，对其运行测试，然后拆除容器。这是 Azure SQL 引擎，不是 SQL Server 映像。

本技能介绍的是在进程内管理引擎生命周期的测试（Testcontainers）。它与 azuresql-db-ci 不同；后者通过工作流 YAML 将同一引擎接入 CI 管道，作为服务容器使用。如果目标是 CI 作业，而不是在代码中设置测试环境，请改用 azuresql-db-ci。

于 2026-09-05 针对容器映像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 完成验证，其报告的 EngineEdition 为 5，Edition 为 SQL Azure，构建版本为 12.0.2000.8。本技能背后的六项可执行检查均已通过：引擎标识、USE 对应的 Msg 40508、容器内的引擎监听 1433（因此可以使用随机映射的主机端口）、连接不会创建数据库、原生 VECTOR(n) 类型，以及等待策略调用的 /opt/mssql-tools18/bin 工具在映像中存在。本次验证未实际运行 Testcontainers 示例。

使用正确的映像（拦截点）

• 使用此引擎映像： sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
• 不要使用 Testcontainers 的 MsSql 预设／MsSqlContainer 模块，它会拉取 mcr.microsoft.com/mssql/server（SQL Server 映像）。请改用通用容器启动上述引擎映像。
• 启动后验证标识：SELECT SERVERPROPERTY('EngineEdition') 返回 5， SERVERPROPERTY('Edition') 返回 'SQL Azure'。
• 映像仅支持 x64。在非 x64 主机上，请将容器平台设为 linux/amd64 （各语言的设置方式有所不同；请参阅示例）。

有关完整的引擎详情（就绪状态、向量、故障排除），请参阅 azuresql-db-container 技能。

映像为私有映像：让 Testcontainers 拉取它

Private Preview 期间，注册表为私有，因此 Docker 完成身份验证前，Testcontainers 无法拉取映像。 请在运行测试的机器上登录一次（或预先拉取映像），并确保在测试主机尝试启动容器前完成：

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # shared pull-only Private Preview creds
docker pull sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest   # optional warm pull

请前往 https://aka.ms/sqldbcontainerpreview-signup 注册以获取拉取凭据；凭据可能会轮换，Private Preview 期间注册表和标签也都是临时的。在 CI 中，请在测试前执行 docker login 步骤（请参阅 azuresql-db-ci）。

每个测试设置都需要注意的四点

1. 容器启动时尚未就绪。 引擎需要几秒钟才能启动。你必须附加等待策略（日志消息、端口或执行 SELECT 1 命令），以免引擎尚未响应时测试就发起连接。不要使用固定时长的 sleep。
2. 引擎不会自动创建数据库。 等待条件满足后，在任何测试使用 Database=appdb 连接之前，先通过 master 连接运行 CREATE DATABASE appdb。Testcontainers 提供的是容器，不是数据库。
3. 切勿使用 USE 切换数据库。 在用户数据库会话中，USE 会返回 Msg 40508，与 Azure 云端 SQL 完全相同。请在连接字符串中选择数据库（Database=appdb）。master 连接仅用于创建数据库。
4. 映射端口；不要假定主机上的端口是 1433。 Testcontainers 会将容器端口 1433 绑定到一个随机空闲的主机端口。请读取映射后的主机端口，并据此构建连接字符串，以免并行测试套件发生端口冲突。

每个配方都遵循的生命周期

1. 使用引擎映像和 ACCEPT_EULA=Y 构建通用容器，并设置复杂的 MSSQL_SA_PASSWORD（字面值示例：YourStr0ng_Passw0rd；至少 8 个字符，且包含大写字母、小写字母、数字和符号中的至少三类）。暴露容器端口 1433。在非 x64 主机上，将映像平台设为 linux/amd64。
2. 附加 wait-for-ready 策略，以便只有在引擎响应后，Start 才返回。
3. 通过 master 连接创建 appdb（执行 SELECT 1，然后运行 IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;）。
4. 使用映射后的主机端口构建连接字符串，并传给测试： Server=localhost,<mappedPort>;Database=appdb;User Id=sa;Password=YourStr0ng_Passw0rd;TrustServerCertificate=true。 项目惯例使用 User Id= / Password= / Database= 这些关键字；文档中记载的 SqlClient 同义词 Uid= / Pwd= 也可正常使用。命令行中 TrustServerCertificate=true 的等效写法是 -C，正如命令行配方所对应的 azuresql-db-container 技能中所述。
5. fixture/测试套件结束时 释放 容器，避免资源泄漏。

根据需要的范围确定容器的生命周期：为了提高速度，每个测试套件/类使用一个容器；为了完全隔离，每个测试使用一个容器。各语言的配方（等待策略、appdb 创建、连接字符串、释放）见 references/testcontainers-snippets.md；确定测试使用的语言后，打开该文件：

• .NET：Testcontainers for .NET + xUnit IAsyncLifetime fixture。
• Node / TypeScript：testcontainers + Jest globalSetup / globalTeardown。
• Python：testcontainers + pytest fixture。
• Java：Testcontainers + JUnit 5 @Container。

向量（如果被测代码使用嵌入）

原生 VECTOR(n) 列类型和 VECTOR_DISTANCE('cosine', a, b)。插入时使用 CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n))，其中 n 必须是字面值，绝不能是绑定参数（维度使用参数会导致“Incorrect syntax near '@P3'”错误）。

验证规则

• 容器由引擎映像启动，绝不使用 Testcontainers MsSql 预设或 mcr.microsoft.com/mssql/server。
• 已附加 wait-for-ready 策略；引擎响应前测试绝不连接，且不使用固定的 sleep。
• 任何测试使用 Database=appdb 连接前，必须先通过 master 连接创建 appdb。
• 使用映射后的主机端口构建连接字符串；字符串使用 User Id=/Password=/Database= 和 TrustServerCertificate=true。
• fixture 或测试套件结束时释放容器。
• 对正在运行的容器，EngineEdition 为 5。
• 如果上述任何验证规则未通过，或者为了完成任务不得不偏离此技能，那么这是此技能中的错误：加载 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”

请勿

• 请勿使用 Testcontainers MsSql 预设映像 mcr.microsoft.com/mssql/server；请通过通用容器启动 Azure SQL 引擎映像。
• 请勿跳过 wait-for-ready 策略；容器启动时，引擎尚未就绪。
• 请勿假设 appdb 已存在；请先通过 master 连接创建它。
• 请勿将主机端口 1433 写死；读取映射后的端口，并据此构建连接字符串。
• 请勿使用 USE appdb 切换数据库；请将数据库名写入连接字符串。
• 请勿将非 x64 主机称为“受支持”，也请勿将向量维度作为绑定参数传递。

参考资料

• references/testcontainers-snippets.md：按语言分类的通用容器示例（.NET/xUnit、Node/Jest、Python/pytest、Java/JUnit 5），涵盖就绪等待策略、appdb 配置、从映射端口获取连接字符串以及释放资源。请阅读适用于你的测试技术栈的示例。

保持最新

本技能所用工具的权威版本锁定参考资料（按需阅读）：

• Testcontainers：用于临时测试容器的多语言库。
• SqlConnection 连接字符串关键字：完整的关键字表。

如果已配置 Microsoft Learn MCP 服务，可使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取上述任一内容的当前版本。此项为可选；若不可用，上述参考资料即为权威来源。