azuresql-db-ci

CI 中的 Azure SQL Database 容器

将 Azure SQL Database 引擎（Private Preview）作为 CI 服务容器运行集成测试。这是本地 Azure SQL 引擎，不是 SQL Server 镜像 mcr.microsoft.com/mssql/server。SELECT SERVERPROPERTY('EngineEdition') 返回 5，而 SERVERPROPERTY('Edition') 返回 'SQL Azure'。如果工作流原本打算使用 SQL Server 镜像，请停止并改用此镜像。

如需了解完整的就绪检查流程、连接方式、向量、数据填充和注册表详情，请加载 azuresql-db-container 技能。

已于 2026-09-05 使用容器镜像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 完成验证，报告的 EngineEdition 为 5，Edition 为 SQL Azure，构建版本为 12.0.2000.8。此技能涉及的 4 项可执行检查均已通过：引擎标识、测试会话连接到用户数据库而非 master、USE 返回 Msg 40508，以及镜像内 /opt/mssql-tools18/bin/sqlcmd 的可用性。此次运行并未执行工作流 YAML；检查的是工作流所依赖的引擎行为。

关键事实（内嵌）

• 镜像： sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64，linux/amd64）。该镜像位于 Private Preview 私有注册表中；运行器必须使用 ACR_USERNAME / ACR_PASSWORD 密钥登录。Private Preview 期间，注册表和标签均为临时信息。
• 平台： 该镜像仅支持 x64。CI 托管运行器为 x64，因此无需在其中指定 --platform 标志。对于非 x64 自托管运行器，请添加 --platform linux/amd64。
• 必需的环境变量： ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD（8 个或更多字符，包含大写字母、小写字母、数字和符号），并将其存储为密钥。引擎监听 1433 端口。
• 先创建 appdb。 引擎不会在连接时自动创建数据库。任何连接使用 Database=appdb 之前，都必须先通过 master 连接执行 CREATE DATABASE appdb。
• 优先使用连接字符串，而非 USE。 避免使用 USE 切换数据库。在用户数据库会话中（这是与 Azure 一致的开发环境），USE 会返回 Msg 40508，与云端 Azure SQL Database 完全相同。master 连接属于配置会话，不会强制执行 Azure 语句筛选器，因此 USE 看起来可以正常工作；但 master 仅用于配置，不用于应用程序工作。始终在连接字符串中选择目标数据库（Database=appdb，或在 sqlcmd 中使用 -d appdb）。
• master 仅用于配置。 测试针对用户数据库 appdb 运行，绝不针对 master。
• 不会自动填充数据。 镜像不会运行 /docker-entrypoint-initdb.d/*.sql（这是 Postgres/MySQL 的惯例，此处不支持）。创建 appdb 后，请通过运行 sqlcmd -d appdb -i seed.sql 来填充数据。

连接字符串（标准）

Server=localhost,1433;Database=appdb;User Id=sa;Password=<MSSQL_SA_PASSWORD>;TrustServerCertificate=true

请写出关键字 User Id= / Password= / Database=。这是本项目的统一风格，因此此集合中的所有示例格式一致。Uid= 和 Pwd= 是有文档说明的 SqlClient 同义词，也可以使用。使用 sqlcmd 时，请使用 -C 信任自签名证书。应用通过单个 SQL_CONNECTION_STRING 环境变量读取此值。测试针对 appdb，而非 master。

GitHub Actions（规范配置）

服务容器会启动引擎。其健康检查会在容器内运行 sqlcmd，因此运行器无需安装客户端工具。测试前，另一个步骤会通过 docker exec 创建 appdb。

name: integration
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      sqldb:
        image: sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
        credentials:
          username: ${{ secrets.ACR_USERNAME }}
          password: ${{ secrets.ACR_PASSWORD }}
        env:
          ACCEPT_EULA: "Y"
          MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}
        ports:
          - "127.0.0.1:1433:1433"
        # Health check runs INSIDE the container; -b makes a SQL error set the exit
        # code so transient startup errors (e.g. Msg 913) are retried, not masked.
        options: >-
          --health-cmd "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P \"$MSSQL_SA_PASSWORD\" -C -b -l 2 -Q \"SELECT 1\""
          --health-interval 5s
          --health-timeout 3s
          --health-retries 20
          --health-start-period 30s
    steps:
      - uses: actions/checkout@v7

      # The engine does NOT auto-create databases. Provision appdb on master first,
      # via docker exec into the service container (runner needs no sqlcmd).
      - name: Provision appdb
        run: |
          CID=$(docker ps --filter "ancestor=sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" --format '{{.ID}}')
          docker exec "$CID" /opt/mssql-tools18/bin/sqlcmd \
            -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b \
            -Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"
        env:
          MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}

      # Optional: seed appdb (no auto-seed). Copy the file in, then run it against appdb.
      - name: Seed appdb
        run: |
          CID=$(docker ps --filter "ancestor=sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest" --format '{{.ID}}')
          docker cp seed.sql "$CID:/tmp/seed.sql"
          docker exec "$CID" /opt/mssql-tools18/bin/sqlcmd \
            -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -d appdb -i /tmp/seed.sql
        env:
          MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}

      - name: Run integration tests
        run: |
          # Tests connect to the USER database appdb, NOT master.
          npm ci && npm run test:integration
        env:
          SQL_CONNECTION_STRING: "Server=localhost,1433;Database=appdb;User Id=sa;Password=${{ secrets.MSSQL_SA_PASSWORD }};TrustServerCertificate=true"

为什么这样选择

• credentials: 使用 ACR_USERNAME / ACR_PASSWORD 密钥从私有预览版 ACR 拉取镜像。没有它，拉取会失败：该注册表是私有的。
• 使用 --health-cmd 和 -l 2 -b 等待服务真正就绪。docker run 返回并不代表引擎已就绪；-b 会重试暂时性的 SQL 启动错误，而不是将其掩盖。作业会在健康检查通过后才运行步骤。
• 使用预配步骤，而非自动创建。 测试打开 Database=appdb 之前，appdb 必须已存在。
• 测试连接指向 appdb。 master 仅用于预配。

必需的密钥

密钥	用途
ACR_USERNAME	登录私有预览版注册表（使用提供给 Private Preview 参与者的共享只读拉取凭据；通过 https://aka.ms/sqldbcontainerpreview-signup 注册获取；凭据可能会轮换）
ACR_PASSWORD	登录私有预览版注册表
MSSQL_SA_PASSWORD	引擎的 sa 密码；必须是复杂密码，至少 8 个字符

适配其他 CI

• Azure Pipelines： 没有原生的 services:。使用 docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io -u $(ACR_USERNAME) -p $(ACR_PASSWORD) 登录，按照下面的规范启动方案运行容器（该方案会在等待就绪的循环中预配 appdb），然后运行测试，并将 SQL_CONNECTION_STRING 指向 appdb。
• GitLab CI： 为镜像配置 services: 条目，为私有注册表设置 DOCKER_AUTH_CONFIG，设置 ACCEPT_EULA 和 MSSQL_SA_PASSWORD，然后在测试前通过 before_script 使用 docker exec（或 sqlcmd 容器）预配 appdb。

规范启动方案（可自托管 / 非服务型运行器）

以一种形式实现释放端口、条件平台设置、等待就绪并预配 appdb：

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"

验证规则

• 拉取镜像时使用 credentials:（或 docker login）和 ACR_USERNAME / ACR_PASSWORD。
• 在服务上设置 ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD（来自密钥）。
• 健康检查使用容器内部的 sqlcmd，并带上 -C -b -l 2。
• 任何测试连接之前，预配步骤会在 master 上创建 appdb。
• 测试用的 SQL_CONNECTION_STRING 包含 Database=appdb，而不是 master。按照项目惯例，登录关键字写作 User Id= / Password=；Uid= / Pwd= 是有效的同义写法，不算错误。
• 如果上述任何验证规则未通过，或者为了让任务运行而不得不偏离此技能的要求，这是此技能中的 bug：加载 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"

请勿

• 请勿使用 SQL Server 镜像 mcr.microsoft.com/mssql/server；应使用 Azure SQL DB 镜像。
• 请勿在 master 上预配 appdb 之前使用 Database=appdb 连接；引擎不会自动创建它。
• 请勿使用 USE appdb 切换数据库；用户数据库会话会返回 Msg 40508，与云端 Azure SQL Database 完全相同。请在连接字符串中选择目标数据库（Database=appdb，或 sqlcmd 使用 -d appdb）。
• 请勿针对 master 运行测试；master 仅用于预配。
• 请勿依赖 /docker-entrypoint-initdb.d/*.sql；它不会生效。请使用 sqlcmd -d appdb -i 填充数据。
• 请勿要求运行器安装 sqlcmd；健康检查和预配都在容器内部运行。
• 请勿将非 x64 主机称为“受支持”；在非 x64 自托管运行器上，只需添加 --platform linux/amd64。

保持信息最新

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

• GitHub Actions 服务容器：介绍服务容器、健康选项和凭据在工作流中的运作方式。
• GitHub 工作流 JSON 架构：工作流 YAML 的权威架构。

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