azuresql-db-scaffold

在 Azure SQL Database 容器上搭建新项目

使用 Azure SQL Database 容器（Private Preview）作为默认本地数据库，快速搭建新应用。这是 Azure SQL 引擎，不是 SQL Server 镜像。

已于 2026-09-05 针对容器镜像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 完成验证，报告的 EngineEdition 为 5，Edition 为 SQL Azure，版本为 12.0.2000.8。此技能背后的三项可执行检查均已通过：引擎标识、USE 返回 Msg 40508，以及通过 NVARCHAR(MAX) 进行双重转换的原生 VECTOR(n) 列。本次运行未执行各技术栈本身的脚手架，因此这些代码片段是根据各自技术栈的文档检查格式，而非端到端实测。

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

• 使用此引擎镜像： sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
• 不要使用 mcr.microsoft.com/mssql/server（SQL Server 镜像）。如果生成的 compose/run 命令指向该镜像，请停止并切换到上述引擎镜像。
• 启动后验证标识：SELECT SERVERPROPERTY('EngineEdition') 返回 5， SERVERPROPERTY('Edition') 返回 'SQL Azure'。
• 镜像仅支持 x64。在非 x64 主机上，添加 --platform linux/amd64（Docker）或 platform: linux/amd64（compose）。
• 注册表为私有（Private Preview）：先使用 Private Preview 参与者共享的只读凭据登录 docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io（注册 https://aka.ms/sqldbcontainerpreview-signup 获取；凭据 可能会轮换）。 Private Preview 期间，注册表和标签均为临时配置。

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

每个脚手架都必须注意的三件事

1. 引擎不会自动创建数据库。连接 Database=appdb 之前，必须在 master 连接上执行 CREATE DATABASE appdb。
2. 避免使用 USE 切换数据库。在用户数据库会话中（这是与 Azure 保持一致的 开发环境），USE 会返回 Msg 40508，与云端 Azure SQL Database 完全一致。master 连接属于预配会话，不会强制执行 Azure 语句过滤器，因此在那里 USE 看似可行，但 master 仅用于预配，不用于应用开发。始终在连接字符串中选择目标数据库 （Database=appdb，或 sqlcmd 使用 -d appdb）。
3. master 连接仅用于预配；实际操作请在用户数据库上进行。

另外：镜像不会自动运行 /docker-entrypoint-initdb.d/*.sql（这是 Postgres/MySQL 的惯例；此处不支持）。预配 appdb 后，使用 sqlcmd -d appdb -i seed.sql 填充初始数据。

步骤 1：启动容器并预配 appdb

请使用以下准确形式（空闲端口、按需指定平台、等待就绪、在同一重试循环中预配 appdb）。-b 会使 SQL 错误设置退出代码，因此启动期间的暂时性错误（例如 Msg 913）会触发重试，而不会被掩盖。切勿在没有 -l 的情况下轮询裸 sqlcmd。

# 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"

必需的环境变量：ACCEPT_EULA=Y 和复杂的 MSSQL_SA_PASSWORD（至少 8 个字符，且至少包含大写字母、小写字母、数字和符号中的三类）。引擎监听 1433 端口。

步骤 2：规范连接字符串

应用读取一个环境变量 SQL_CONNECTION_STRING（如果 1433 端口已被占用，请将 1433 替换为步骤 1 选择的 HOST_PORT）：

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

约定的写法使用 User Id= / Password= / Database= 关键字；Uid= / Pwd= 是文档记录的 SqlClient 同义词，同样可用。使用 sqlcmd 时，请指定 -C 以信任自签名证书。对于 Prisma（NestJS / Next.js），同一实例也可通过 DATABASE_URL 中的 sqlserver:// URL 表示（请参阅代码片段）。

第 3 步：选择技术栈

每种技术栈的脚手架代码片段（compose 服务、.env、创建 appdb、首次迁移、使用参数化查询的类型化数据访问层）位于 references/scaffold-snippets.md；确定要为哪种技术栈搭建脚手架后，请打开该文件：

• .NET Aspire（EF Core）
• FastAPI（SQLAlchemy / pyodbc）
• Next.js（Prisma，sqlserver:// DATABASE_URL）
• NestJS（Prisma 或 TypeORM）

第 4 步：首次迁移和填充数据

该骨架会通过技术栈的迁移工具创建架构。完整的迁移工作流（幂等脚本、排序、在就绪等待循环中应用）请参阅 azuresql-db-schema-migration 技能。对于 Next.js 或 NestJS 骨架，内容如下：

npx prisma migrate dev --name init

仅在 appdb 存在后填充数据：

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

向量（如果应用使用嵌入）

原生 VECTOR(n) 列类型和 VECTOR_DISTANCE('cosine', a, b)。插入时使用 CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n))，其中 n 必须是字面值，不能是绑定参数（维度参数 会导致错误 "Incorrect syntax near '@P3'"）。CREATE VECTOR INDEX（DiskANN）可在此映像上正常工作，且经过实测；已知 限制页面对此也有说明。它需要 SET QUOTED_IDENTIFIER ON，并且至少要有 100 行非空向量（少于此数量时会出现 Msg 42266）。对于小型表，全表扫描 top-k 仍然精确，也仍是正确的选择。azuresql-db-rag 技能包含该索引施加的规则。

验证规则

• Compose/运行的目标是引擎映像，绝不是 mcr.microsoft.com/mssql/server。
• 在任何应用/迁移连接 Database=appdb 之前，必须先通过 master 连接创建 appdb。
• 应用读取 SQL_CONNECTION_STRING（以及 ORM 需要时读取 DATABASE_URL）；连接字符串使用 User Id=/Password=/Database=。
• 所有数据访问都使用参数化查询；向量维度 n 必须是字面值。
• 对运行中的容器，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"

请勿

• 请勿使用 SQL Server 映像，也不要将非 x64 主机称为“受支持”。
• 请勿依赖自动创建数据库或 /docker-entrypoint-initdb.d/*.sql 自动填充数据。
• 请勿使用 USE appdb 切换数据库；应将其写入连接字符串。
• 请勿在不带 -l 的情况下轮询裸 sqlcmd；请勿将向量维度作为绑定参数传递。
• 请勿在应用配置中硬编码 1433；请将所选的 HOST_PORT 读入连接字符串。

参考资料

• references/scaffold-snippets.md：共享的 compose 服务以及各技术栈的骨架（.NET Aspire/EF Core、FastAPI、Next.js/Prisma、NestJS），包含 .env、appdb 创建、首次迁移和参数化数据访问层。确定要为哪种技术栈搭建脚手架后，请阅读此文件。

保持信息最新

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

• Prisma 与 SQL Server：SQL Server 连接器、数据源 URL 和类型映射。
• EF Core 迁移：添加/更新迁移、历史记录表和幂等脚本。
• Docker Compose 文件参考：服务、健康检查和 depends_on 语法所遵循的 Compose 规范。
• SqlConnection 连接字符串关键字：完整的连接字符串关键字表。

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