azuresql-db-schema-migration

Azure SQL Database 容器上的架构迁移

像在云端一样，将架构迁移应用到本地 Azure SQL Database 容器，确保开发环境和生产环境保持一致。这是 Azure SQL Database 引擎（SELECT SERVERPROPERTY('EngineEdition') 返回 5，Edition 返回 'SQL Azure'），不是 SQL Server 映像 mcr.microsoft.com/mssql/server。如果某个工具或模板指向 SQL Server 映像，请停止使用，并改用下面的映像。

已于 2026-09-05 使用容器映像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 验证，该映像报告 EngineEdition 为 5，Edition 为 SQL Azure，build 为 12.0.2000.8。此技能涉及的六项可执行检查均已通过：引擎标识、USE 返回 Msg 40508、迁移 DDL 中的 VECTOR(n) 列、SqlPackage 170.4.83.3 自带帮助中列出的三个 Publish 参数和 /TargetTrustServerCertificate，以及在 Entity Framework Core .NET 命令行工具 9.0.19 上运行 dotnet ef database update。

每种迁移工具都会遇到的一个问题

引擎不会在连接时自动创建数据库。每种迁移工具都假设目标数据库已经存在。因此：

1. 先在 master 连接上创建 appdb。
2. 然后将迁移工具指向用户数据库（Database=appdb）。

避免使用 USE 切换数据库。在用户数据库会话中（这是开发时与 Azure 保持一致的上下文），USE 会返回 Msg 40508，与云端 Azure SQL Database 中的行为完全相同。master 连接是用于预配的会话，不会强制执行 Azure 语句筛选器，因此 USE 看起来可以正常工作，但 master 仅用于预配，不用于应用程序工作。始终在连接字符串中选择目标数据库（Database=appdb；对于 sqlcmd，则使用 -d appdb）。master 连接仅用于预配；请针对 appdb 运行迁移。

启动容器并预配 appdb（标准步骤）

运行 docker run 后，引擎不会立即就绪。使用重试循环等待，并在同一循环中创建 appdb。映像仅支持 x64；在非 x64 主机上，该步骤会自动添加 --platform linux/amd64。Private Preview 期间，注册表为私有，因此请先登录。

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io   # pull-only creds by signing up at https://aka.ms/sqldbcontainerpreview-signup

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

-C 用于信任自签名证书；-b 会让 SQL 错误设置退出代码，这样就能重试临时启动错误（如 Msg 913），而不是将其掩盖。切勿不带 -l 轮询裸 sqlcmd。完整的生命周期详情请参阅 azuresql-db-container 技能。

连接字符串规范

统一使用一种格式，并从单个 SQL_CONNECTION_STRING 环境变量读取：

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

• 按团队规范使用关键字 User Id= / Password= / Database=。Uid= / Pwd= 是有文档说明的 SqlClient 同义词，也可以使用。
• 迁移和应用程序工作使用 Database=appdb，绝不要使用 master。
• 本地自签名证书使用 TrustServerCertificate=true。
• 如果上面选择了非默认的 HOST_PORT，请使用 Server=localhost,<HOST_PORT>。

应用迁移（按工具分类）

在使用以下任何工具之前，先预配 appdb（如上所述）。各工具的完整选项、环境变量配置和故障排查说明，请参阅 references/migration-tools.md。

EF Core（.NET）

export SQL_CONNECTION_STRING="Server=localhost,1433;Database=appdb;User Id=sa;Password=${MSSQL_SA_PASSWORD};TrustServerCertificate=true"
dotnet ef database update

只有在你的账户有权创建数据库时，EF Core 的 EnsureCreated/Migrate 才会创建 appdb；先在 master 上预配是可靠的做法。设计时工厂和 CI（migrations bundle）形式请参阅参考资料。

Prisma（Node）

Prisma 需要在 DATABASE_URL 中使用 sqlserver:// URL 格式：

npm install -D prisma@6
npm install @prisma/client@6
export DATABASE_URL="sqlserver://localhost:1433;database=appdb;user=sa;password=${MSSQL_SA_PASSWORD};trustServerCertificate=true"
npx prisma migrate deploy          # apply committed migrations (CI / prod-like)
npx prisma migrate dev --name init # author + apply a new migration (local dev)

保留 @6。Prisma 7 是当前稳定版本（7.10.0），并且会拒绝下面的 url = env("DATABASE_URL") 数据源配置块：prisma migrate 会在验证时停止，并显示“The datasource property url is no longer supported in schema files”。Prisma 7 将连接 URL 移至 prisma.config.ts，并要求客户端使用驱动适配器（@prisma/adapter-mssql），因此这是配置变更，而不是版本升级。请明确固定主版本，不要让 npm 自行选择：prisma 的 latest dist-tag 曾包含 8.x 预发行版本。Prisma 7 的配置方式请参阅参考资料。

Alembic（Python）

export SQL_CONNECTION_STRING="mssql+pyodbc://sa:${MSSQL_SA_PASSWORD}@localhost,1433/appdb?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
alembic upgrade head

SqlPackage / DACPAC

sqlpackage /Action:Publish /SourceFile:./app.dacpac \
  /TargetServerName:"localhost,1433" /TargetDatabaseName:appdb \
  /TargetUser:sa /TargetPassword:"$MSSQL_SA_PASSWORD" \
  /TargetTrustServerCertificate:true

迁移中的向量

引擎具有原生 VECTOR(n) 列类型和 VECTOR_DISTANCE('cosine', a, b)。 在迁移中，维度 n 必须是 DDL 中的字面值（embedding VECTOR(1536)）。 通过 CAST(CAST(? AS NVARCHAR(MAX)) AS VECTOR(n)) 插入时，n 必须是字面值，不能是绑定参数（参数化维度会报错：“Incorrect syntax near '@P3'”）；内部的 NVARCHAR(MAX) 转换可避免将实际嵌入向量的 JSON 作为 ntext 发送，而引擎会拒绝 ntext（错误 529）。 CREATE VECTOR INDEX（DiskANN）在此映像上可用，并经过了实测，Known limitations 页面也对此有说明。迁移时有三点需要注意：

• 执行 DDL 的会话需要设置 SET QUOTED_IDENTIFIER ON，并且在非空向量行数少于 100 行时无法创建索引（Msg 42266）。因此，索引应放在语料加载之后执行的迁移步骤中，而不是与 CREATE TABLE 放在一起。
• 索引存在时，TRUNCATE TABLE 会被拒绝（Msg 42232）。重新加载表的迁移必须先删除索引，而且 DROP VECTOR INDEX 并不是一条语句：请使用 DROP INDEX name ON dbo.table。
• Microsoft Learn 说明，向量索引无法通过数据层包导入保留，因为导入会先创建架构，再加载行，之后索引创建会因未达到 100 行的最低要求而失败。导出前请删除向量索引，并在导入后重新创建。

对于小表，全表扫描 top-k 仍能得到精确结果，也仍是正确的选择。

迁移后填充数据

此映像不会自动运行 /docker-entrypoint-initdb.d/*.sql（这是 Postgres/MySQL 的惯例，但此处不适用）。迁移后请显式填充数据：

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

验证规则

• 迁移工具运行前，master 中已存在 appdb。
• 迁移工具的目标是 Database=appdb，而不是 master。
• 连接字符串使用 User Id=/Password=/Database= 和 TrustServerCertificate=true。
• 任何地方都不要使用 USE appdb；请在连接字符串中选择数据库。在用户数据库会话中，USE 会返回 Msg 40508，与云端 Azure SQL Database 中的情况完全一致；它似乎只在用于预配的 master 会话中有效，而该会话仅用于预配。
• 使用 -b -l 运行了就绪等待循环；容器在迁移前报告“ready”。
• 如果上述验证规则有任何一条未通过，或为了让任务成功而不得不偏离此技能，则说明此技能存在问题：加载 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。
• 不要指望连接时自动创建数据库。
• 不要使用 USE <db> 切换数据库。
• 不要依赖 /docker-entrypoint-initdb.d/ 自动填充数据。
• 不要称非 x64 主机为“受支持”；在非 x64 主机上只需添加 --platform linux/amd64。
• 不要将向量维度作为绑定参数传递。
• 不要使用 master 连接运行迁移。

参考资料

• references/migration-tools.md：各工具的完整接线配置（EF Core、Prisma、Alembic、SqlPackage）、环境变量设置和常见迁移故障。当工具所需配置超出上文所示命令，或迁移失败时，请阅读此文档。

保持最新

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

• EF Core migrations：添加/更新迁移、历史记录表和幂等脚本。
• Prisma with SQL Server：SQL Server 连接器、数据源 URL 和类型映射。
• Alembic：SQLAlchemy 迁移：env.py、自动生成和升级/降级。
• SqlPackage import：.bacpac/.dacpac 的 Import 和 Publish 参数。

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