azuresql-db-ci
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThe Azure SQL Database container in CI
CI 中的 Azure SQL Database 容器
Run integration tests against the Azure SQL Database engine (Private Preview) as a CI
service container. This is the local Azure SQL engine, not the SQL Server image
. returns 5 and
returns 'SQL Azure'. If a workflow was about to use the SQL Server image, stop and use this image instead.
mcr.microsoft.com/mssql/serverSELECT SERVERPROPERTY('EngineEdition')SERVERPROPERTY('Edition')For the full readiness loop, connection model, vectors, seeding, and registry detail, load the
azuresql-db-container skill.
针对 Azure SQL Database 引擎(Private Preview)运行集成测试,并将其作为 CI
service container 使用。这是本地 Azure SQL 引擎,而不是 SQL Server 镜像
。 返回 5,
返回 'SQL Azure'。如果某个 workflow 即将使用 SQL Server 镜像,请停止并改用此镜像。
mcr.microsoft.com/mssql/serverSELECT SERVERPROPERTY('EngineEdition')SERVERPROPERTY('Edition')如需了解完整的 readiness loop、连接模型、向量、数据初始化和 registry 详情,请加载
azuresql-db-container skill。
Load-bearing facts (inlined)
关键事实(内联)
- Image: (x64, linux/amd64). It lives in a private preview registry; the runner must sign in with
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest/ACR_USERNAMEsecrets. Registry and tag are provisional during Private Preview.ACR_PASSWORD - Platform: the image is x64 only. CI hosted runners are x64, so no
flag is needed there. On a non-x64 self-hosted runner, add
--platform.--platform linux/amd64 - Required env: and a complex
ACCEPT_EULA=Y(8+ chars, upper/lower/digit/ symbol), kept in a secret. Engine listens on 1433.MSSQL_SA_PASSWORD - Provision appdb first. The engine does NOT auto-create databases on connect. You must
on a master connection before anything connects with
CREATE DATABASE appdb.Database=appdb - Prefer the connection string over . Avoid
USEto 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 - master is for provisioning only. Tests run against the user database , never master.
appdb - No auto-seed. The image does NOT run (that is a Postgres/MySQL convention, not honored here). Seed by running
/docker-entrypoint-initdb.d/*.sqlafter provisioning appdb.sqlcmd -d appdb -i seed.sql
- 镜像: (x64、linux/amd64)。它位于私有预览 registry;runner 必须使用
sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest/ACR_USERNAMEsecrets 登录。Private Preview 期间,registry 和 tag 仍是暂定值。ACR_PASSWORD - 平台: 该镜像仅支持 x64。CI 托管 runner 均为 x64,因此无需在那里添加
标志。在非 x64 的 self-hosted runner 上,请添加
--platform。--platform linux/amd64 - 必需环境变量: ,以及一个复杂的
ACCEPT_EULA=Y(8 个以上字符,包含大写字母、小写字母、数字和 符号),并保存在 secret 中。引擎监听 1433 端口。MSSQL_SA_PASSWORD - 必须先预配 appdb。 引擎在连接时不会自动创建数据库。在任何使用
的连接建立之前,必须先通过 master connection 执行
Database=appdb。CREATE DATABASE appdb - 优先使用连接字符串,而不是 。 避免使用
USE切换数据库。在用户数据库 session(也就是你进行开发时与 Azure 行为保持一致的上下文)中,USE会返回USE,与云端 Azure SQL Database 中的行为完全一致。Msg 40508connection 是预配 session, 其中不会强制执行 Azure 语句过滤器,因此master在那里似乎可以正常工作, 但USE仅用于预配,不用于应用工作。始终在连接字符串中选择目标数据库 (master,或者在 sqlcmd 中使用Database=appdb)。-d appdb - master 仅用于预配。 测试应针对用户数据库 运行,绝不能针对 master 运行。
appdb - 不会自动初始化数据。 该镜像不会运行 (这是 Postgres/MySQL 的约定,此处不支持)。预配 appdb 后,通过运行
/docker-entrypoint-initdb.d/*.sql初始化数据。sqlcmd -d appdb -i seed.sql
Connection string (standard)
连接字符串(标准)
Server=localhost,1433;Database=appdb;User Id=sa;Password=<MSSQL_SA_PASSWORD>;TrustServerCertificate=trueSpell the keywords / / . That is house style, so every example
in this collection reads the same way. and are documented SqlClient synonyms and
work too. For sqlcmd use to trust the
self-signed cert. The app reads this from a single env var. Tests target
, not master.
User Id=Password=Database=Uid=Pwd=-CSQL_CONNECTION_STRINGappdbServer=localhost,1433;Database=appdb;User Id=sa;Password=<MSSQL_SA_PASSWORD>;TrustServerCertificate=true请拼写关键字 / / 。这是本套示例的内部规范,因此
本合集中的每个示例写法都保持一致。 和 是文档中列出的 SqlClient 同义词,
同样可以使用。对于 sqlcmd,请使用 信任自签名证书。
应用从单个 环境变量中读取此值。测试应针对 ,而不是 master。
User Id=Password=Database=Uid=Pwd=-CSQL_CONNECTION_STRINGappdbGitHub Actions (canonical)
GitHub Actions(标准示例)
The service container starts the engine. Its health check runs sqlcmd inside the container, so
the runner needs no client tools. A separate step provisions via before tests.
appdbdocker execyaml
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 }}
SQLCMDPASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}
ports:
- 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 -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 -C -b \
-Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"
# 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 -C -b -d appdb -i /tmp/seed.sql
- 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"service container 会启动引擎。它的健康检查会在容器内部运行 sqlcmd,因此
runner 不需要安装任何客户端工具。测试之前,需要通过单独的步骤使用 预配 。
docker execappdbyaml
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 }}
SQLCMDPASSWORD: ${{ secrets.MSSQL_SA_PASSWORD }}
ports:
- 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 -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 -C -b \
-Q "IF DB_ID('appdb') IS NULL CREATE DATABASE appdb;"
# 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 -C -b -d appdb -i /tmp/seed.sql
- 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"Why these choices
为什么采用这些选择
- pulls from the private preview ACR using
credentials:/ACR_USERNAMEsecrets. Without it the pull fails: the registry is private.ACR_PASSWORD - with
--health-cmdwaits for true readiness.-l 2 -breturning does not mean the engine is ready;docker runretries transient SQL startup errors instead of masking them. The job blocks on health before steps run.-b - Provision step, not auto-create. appdb must exist before tests open .
Database=appdb - Test connection targets appdb. master is for provisioning only.
- 使用
credentials:/ACR_USERNAMEsecrets 从私有预览 ACR 拉取镜像。如果不配置此项,拉取将失败,因为该 registry 是私有的。ACR_PASSWORD - 带 的
-l 2 -b会等待真正就绪。--health-cmd返回并不表示 引擎已经就绪;docker run会重试临时性的 SQL 启动错误,而不是掩盖错误。 在步骤运行之前,job 会等待健康检查通过,因此会被阻塞。-b - 使用预配步骤,而不是自动创建。 在测试使用 建立连接之前,appdb 必须已经存在。
Database=appdb - 测试连接以 appdb 为目标。 master 仅用于预配。
Required secrets
必需的 Secrets
| Secret | Purpose |
|---|---|
| Private preview registry sign-in (using the shared pull-only credentials provided to the Private Preview cohort; get them by signing up at https://aka.ms/sqldbcontainerpreview-signup; they may rotate) |
| Private preview registry sign-in |
| sa password for the engine; complex, 8+ chars |
| Secret | 用途 |
|---|---|
| 登录私有预览 registry(使用提供给 Private Preview 用户群的共享仅拉取凭据;可通过 https://aka.ms/sqldbcontainerpreview-signup 注册获取;凭据可能会轮换) |
| 登录私有预览 registry |
| 引擎的 sa 密码;必须复杂,长度不少于 8 个字符 |
Adapting to other CI
适配其他 CI
- Azure Pipelines: there is no native . Sign in and run the canonical start recipe below (it provisions appdb in the ready-wait loop) in one Bash task:
services:Then run tests withyaml- bash: | printf '%s' "$ACR_PASSWORD" | docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io --username "$ACR_USERNAME" --password-stdin # Run the canonical start recipe below in this task. env: ACR_USERNAME: $(ACR_USERNAME) ACR_PASSWORD: $(ACR_PASSWORD) MSSQL_SA_PASSWORD: $(MSSQL_SA_PASSWORD)pointed at appdb.SQL_CONNECTION_STRING - GitLab CI: use a entry for the image, set
services:for the private registry, setDOCKER_AUTH_CONFIG, and map a maskedACCEPT_EULAvariable to bothMSSQL_SA_PASSWORD_UIandMSSQL_SA_PASSWORD, then provision appdb in aSQLCMDPASSWORDwithbefore_script(or a sqlcmd container) before tests.docker exec
- Azure Pipelines: 没有原生的 支持。请在一个 Bash 任务中登录并运行下方的标准启动方案, 该方案会在就绪等待循环中预配 appdb:
services:然后运行测试,并将yaml- bash: | printf '%s' "$ACR_PASSWORD" | docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io --username "$ACR_USERNAME" --password-stdin # Run the canonical start recipe below in this task. env: ACR_USERNAME: $(ACR_USERNAME) ACR_PASSWORD: $(ACR_PASSWORD) MSSQL_SA_PASSWORD: $(MSSQL_SA_PASSWORD)指向 appdb。SQL_CONNECTION_STRING - GitLab CI: 为镜像使用 条目,为私有 registry 设置
services:,设置DOCKER_AUTH_CONFIG,并将经过掩码处理的ACCEPT_EULA变量同时映射到MSSQL_SA_PASSWORD_UI和MSSQL_SA_PASSWORD,然后在测试之前通过SQLCMDPASSWORD(或 sqlcmd 容器)在docker exec中预配 appdb。before_script
Canonical start recipe (self-hosted / non-service runners)
标准启动方案(self-hosted / 非 service runner)
Free port, conditional platform, ready-wait, provision appdb in one shape:
bash
(
set +x
: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD in the CI secret store and map it into this step}"
export SQLCMDPASSWORD="$MSSQL_SA_PASSWORD"
HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
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 -e SQLCMDPASSWORD \
-p "$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 -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"
)在一个脚本中完成端口分配、按需指定平台、等待就绪和预配 appdb:
bash
(
set +x
: "${MSSQL_SA_PASSWORD:?Set MSSQL_SA_PASSWORD in the CI secret store and map it into this step}"
export SQLCMDPASSWORD="$MSSQL_SA_PASSWORD"
HOST_PORT=1433; while lsof -nP -iTCP:"$HOST_PORT" -sTCP:LISTEN >/dev/null 2>&1; do HOST_PORT=$((HOST_PORT+1)); done
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 -e SQLCMDPASSWORD \
-p "$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 -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"
)Validation rules
验证规则
- The pull uses (or
credentials:) withdocker login/ACR_USERNAME.ACR_PASSWORD - and a complex
ACCEPT_EULA=Y(from a secret) are set on the service.MSSQL_SA_PASSWORD - The health check runs sqlcmd inside the container with .
-C -b -l 2 - A provisioning step creates on master before any test connects.
appdb - The test has
SQL_CONNECTION_STRING, not master. It spells the login keywordsDatabase=appdb/User Id=as house style;Password=/Uid=are valid synonyms, so they are not a failure.Pwd= - 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"
- 拉取操作使用 (或
credentials:),并提供docker login/ACR_USERNAME。ACR_PASSWORD - 在 service 上设置 和来自 secret 的复杂
ACCEPT_EULA=Y。MSSQL_SA_PASSWORD - 健康检查在容器内部使用 运行 sqlcmd。
-C -b -l 2 - 在任何测试连接之前,预配步骤都会在 master 上创建 。
appdb - 测试使用的 包含
SQL_CONNECTION_STRING,而不是 master。它按照内部规范拼写登录关键字Database=appdb/User Id=;Password=/Uid=也是有效的同义词,因此不算验证失败。Pwd= - 如果上述任一验证规则失败,或者你不得不偏离本 skill 才能使任务运行,则说明本 skill 存在 bug:请加载 azuresql-db-feedback skill,并主动提出提交报告。
- 当上述所有规则均通过且任务完成时,每个 session 仅以一行结束,不要提问或等待回复:"成功了。如果其中有任何不顺利之处,或者你想分享你构建的内容:https://aka.ms/sql-agent-skills-feedback"
Minimum tool versions
最低工具版本
Use only the tools needed by the selected recipe, at or above these minimum versions:
- : go-sqlcmd 1.10.0
sqlcmd
Verify the installed commands before changing resources:
bash
sqlcmd --versionA missing command, an older version, or a nonzero version check is a prerequisite failure.
仅使用所选方案需要的工具,且版本不得低于以下最低版本:
- :go-sqlcmd 1.10.0
sqlcmd
在更改资源之前,先验证已安装的命令:
bash
sqlcmd --version如果命令缺失、版本过旧或版本检查返回非零值,则属于前置条件失败。
Check it worked
检查是否成功
- Positive verification: Require the workflow test command to exit zero and the readiness query to return the expected engine and application database.
- Cleanup verification: Require the service container, temporary database files, and workflow-owned network to be removed after the job.
- Report success only after both observations pass.
- 正向验证: 要求 workflow 的测试命令以零状态退出,并且就绪查询返回预期的引擎和应用程序数据库。
- 清理验证: 要求在 job 结束后删除 service container、临时数据库文件以及 workflow 所拥有的网络资源。
- 只有两项观察均通过后,才能报告成功。
Do not
禁止事项
- Do not use the SQL Server image ; use the Azure SQL DB image.
mcr.microsoft.com/mssql/server - Do not connect with before provisioning appdb on master; the engine will not auto-create it.
Database=appdb - 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 run tests against master; master is for provisioning only.
- Do not rely on ; it is not honored. Seed with
/docker-entrypoint-initdb.d/*.sql.sqlcmd -d appdb -i - Do not require sqlcmd on the runner; the health check and provisioning run inside the container.
- Do not call a non-x64 host "supported"; on a non-x64 self-hosted runner just add .
--platform linux/amd64
- 不要使用 SQL Server 镜像 ;请使用 Azure SQL DB 镜像。
mcr.microsoft.com/mssql/server - 不要在 master 上预配 appdb 之前使用 建立连接;引擎不会自动创建该数据库。
Database=appdb - 不要使用 切换数据库;用户数据库 session 会返回
USE appdb,与云端 Azure SQL Database 中的行为完全一致。请在连接字符串中选择目标 数据库(Msg 40508,或者在 sqlcmd 中使用Database=appdb)。-d appdb - 不要针对 master 运行测试;master 仅用于预配。
- 不要依赖 ;该机制不受支持。请使用
/docker-entrypoint-initdb.d/*.sql初始化数据。sqlcmd -d appdb -i - 不要要求 runner 安装 sqlcmd;健康检查和预配操作都应在容器内部运行。
- 不要将非 x64 主机称为“受支持”;在非 x64 的 self-hosted runner 上,只需添加 。
--platform linux/amd64
Staying current
保持最新
Authoritative, version-pinned references for the tools this skill uses (read the one you need):
- GitHub Actions service containers: how service containers, health options, and credentials work in a workflow.
- GitHub workflow JSON schema: the authoritative schema for workflow YAML.
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 所用工具的权威且版本固定的参考资料(按需读取):
- GitHub Actions service containers:介绍 workflow 中 service containers、health options 和 credentials 的工作方式。
- GitHub workflow JSON schema:workflow YAML 的权威 schema。
如果已配置 Microsoft Learn MCP 服务,请使用 或 按需获取这些工具的最新版本。
此操作是可选的;如果该服务不可用,以上参考资料即为权威来源。
mcp__microsoft-learn__microsoft_docs_searchmcp__microsoft-learn__microsoft_docs_fetch