azuresql-db-from-sql-server

从 SQL Server 映像迁移到 Azure SQL Database 容器

此技能可将现有的本地 SQL Server 设置（SQL Server 映像 mcr.microsoft.com/mssql/server）转换为 Azure SQL Database 容器，让本地开发环境的行为与 Azure SQL Database 一致。两者使用的并非同一数据库引擎：

	SQL Server 映像	Azure SQL Database 容器
映像	mcr.microsoft.com/mssql/server	sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest
SERVERPROPERTY('EngineEdition')	2/3/4/8	5
SERVERPROPERTY('Edition')	例如 'Developer Edition'	'SQL Azure'
数据库模型	一个实例，多个数据库，USE 可用	仅用 master 进行预配；使用用户数据库开展工作；在用户数据库会话中执行 USE 会返回 Msg 40508，与云端完全一致；master 连接是预配会话，不会强制执行此筛选

如果项目正在使用 SQL Server 映像，但希望本地开发环境忠实模拟 Azure，请停止使用该映像并切换到此容器。 此技能独立完整； 如需了解容器的完整详情，请参阅 azuresql-db-container 技能。

已于 2026-09-05 使用容器映像 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest 完成验证，报告的 EngineEdition 为 5、Edition 为 SQL Azure、构建版本为 12.0.2000.8。此技能涵盖的全部九项可执行检查均已通过，包括 USE 返回 Msg 40508、BACKUP 返回 Msg 40510、sp_configure 返回 Msg 2812（不存在，而非被拒绝）、ALTER DATABASE ... SET RECOVERY 返回 Msg 40517、单数据库模型、不会自动运行 /docker-entrypoint-initdb.d，以及位于 /opt/mssql-tools18/bin/sqlcmd 的 sqlcmd。

适用场景

• 项目 Dockerfile、compose 文件或运行脚本引用了 mcr.microsoft.com/mssql/server 或 mssql/server。
• 项目配置了 sqlcmd 和 SA 密码，或者有人提到“Docker 中的 SQL Server”或“本地 mssql 容器”。
• 用户要求“在本地运行 SQL Server”，但实际目标是 Azure SQL Database。

迁移步骤

1. 检测 SQL Server 用法

在仓库中搜索 SQL Server 映像及随之使用的模式：

grep -rniE 'mcr\.microsoft\.com/mssql/server|mssql/server|ACCEPT_EULA|MSSQL_SA_PASSWORD|SA_PASSWORD|sqlcmd|Server=localhost,1433|Database=master' . 2>/dev/null

任何匹配项都是下文中需要改写的候选项。

2. 登录预览注册表

此映像位于私有预览注册表中；使用注册时提供的共享只读拉取凭据登录一次，注册地址为 https://aka.ms/sqldbcontainerpreview-signup（预览期间凭据可能会轮换）：

docker login sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io

私有预览期间，注册表和标签均为临时设置。

3. 改写映像并添加 --platform

将 SQL Server 映像替换为 Azure SQL Database 映像。Azure 映像仅支持 x64，因此在非 x64 主机上添加 --platform linux/amd64 （Docker）或 platform: linux/amd64（compose）。

• 旧版：mcr.microsoft.com/mssql/server:2022-latest
• 新版：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest

保留 ACCEPT_EULA=Y、复杂的 MSSQL_SA_PASSWORD、SA 登录名和端口 1433。请参阅 references/migrate-compose.md 中的 compose 改写前后对比。

4. 启动容器并先预配 appdb

引擎不会在连接时自动创建数据库，而且在 docker run 返回后也不会立即就绪。请使用标准启动方案：该方案会选择一个空闲的主机端口、仅在非 x64 主机上添加 --platform、使用重试循环等待就绪，并在同一循环中预配 appdb。-b -l 2 标志会使 SQL 错误设置退出代码，这样启动过程中的暂时性错误（例如 Msg 913）会触发重试，而不会被掩盖。

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"

master 连接仅用于预配；实际工作请在 appdb 上进行。

5. 将连接字符串从 master 改为用户数据库

SQL Server 项目通常会直接连接到 master（或依赖 SQL Server 自动创建的数据库）。Azure SQL Database 不会自动创建数据库。请在连接字符串中选择目标数据库（Database=appdb，或在 sqlcmd 中使用 -d appdb）。避免使用 USE 切换数据库。在用户数据库会话中（即开发时遵循 Azure 行为的上下文），USE 会返回 Msg 40508，这与云端 Azure SQL Database 完全一致。连接 master 属于预配会话，不会强制执行 Azure 语句筛选，因此在该处 USE 看起来可以正常工作；但 master 仅用于预配，不用于应用程序工作。统一使用一个 SQL_CONNECTION_STRING 环境变量：

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

项目代码风格规定关键字写作 User Id= / Password= / Database=，以保持示例一致。Uid= 和 Pwd= 是文档所述的 SqlClient 同义写法，也可以使用。使用 sqlcmd 时，请用 -C 信任自签名证书，并用 -d appdb 选择数据库。

6. 在预配之后填充种子数据（不使用自动初始化目录）

该映像不会自动运行 /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 -d appdb -i /dev/stdin < seed.sql

7. 移除 SQL Server 专有功能

某些功能仅存在于 SQL Server 映像中，必须移除或替换。请标记并修复所有相关项。如果遇到此列表未提及的功能，请查阅 references/sql-server-vs-azure-feature-matrix.md。

• SQL Server Agent 作业：不可用；请使用外部调度器。
• FILESTREAM / FileTable：不支持；请将二进制对象存储在列中或外部存储中。
• 完整 Service Broker 实例间消息传递：不支持。
• 跨服务器分布式事务（MS DTC、链接服务器）：不支持。
• Windows Auth / NTLM / Integrated Security：不支持；请使用 SA / SQL 身份验证。
• 使用 sp_configure 进行实例级调优：该过程不存在，并非被阻止。调用它会返回 Msg 2812（“Could not find stored procedure 'sp_configure'”），这是对象缺失，而非拒绝访问，因此无需授予权限，也没有可解除的标记。删除继承的调优步骤；此引擎不支持将其转换为其他操作。
• BACKUP / RESTORE：在所有会话中都会被拒绝，并返回 Msg 40510，这与云端 Azure SQL Database 完全一致。.bak 不能用于迁移到此引擎；请使用 SqlPackage 和 bacpac 或 dacpac（参见 azuresql-db-import 技能）。
• ALTER DATABASE ... SET RECOVERY：会被拒绝并返回 Msg 40517，这是另一种拒绝形式。ALTER DATABASE SET 本身受支持，仅此选项被拒绝，因此移植过来的配置脚本可能部分执行成功，导致数据库处于无人预期的状态。请删除恢复模式步骤。

8. 验证标识

确认当前使用的是 Azure SQL Database 引擎：

docker exec -i sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -d appdb \
  -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition, SERVERPROPERTY('Edition') AS Edition;"

预期 EngineEdition = 5 且 Edition = SQL Azure。

向量（如果项目使用嵌入）

Azure SQL Database 引擎原生支持 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 技能涵盖了该索引施加的规则。

验证规则

• 镜像是 sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest，不是 mcr.microsoft.com/mssql/server。
• 在任何应用连接到 appdb 之前，先通过 master 连接创建 appdb。
• 应用连接字符串使用 Database=appdb，实际工作中绝不使用 Database=master。
• 不使用 USE <db> 语句：在用户数据库会话中，USE 会返回 Msg 40508，与云中的 Azure SQL Database 完全相同；master 连接是预配会话，不受此限制，但 master 仅用于预配。应在连接字符串中选择数据库。
• 仅在非 x64 主机上添加 --platform linux/amd64。
• 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"

请勿

• 不要保留 mcr.microsoft.com/mssql/server；它是不同的引擎。
• 不要依赖数据库自动创建，也不要依赖 /docker-entrypoint-initdb.d/*.sql。
• 不要使用 USE appdb；应在连接字符串中选择数据库。
• 不要将非 x64 主机称为“受支持”；仅在非 x64 主机上添加 --platform linux/amd64。
• 在 .NET 风格字符串中优先使用 User Id= / Password=。这是项目规范，并非强制要求：Uid= / Pwd= 是有效的同义写法。
• 不要将向量维度作为绑定参数传递。
• 不要保留 SQL Agent、FILESTREAM、完整的 Service Broker、跨服务器分布式事务或 Windows Auth。
• 不要尝试寻找能让 sp_configure 运行的权限或标志。Msg 2812 表示该过程不存在，因此没有可授予的权限。
• 不要沿用 BACKUP/RESTORE 步骤（Msg 40510）或 ALTER DATABASE ... SET RECOVERY 步骤（Msg 40517）。

参考资料

• references/sql-server-vs-azure-feature-matrix.md：说明哪些内容可以沿用、哪些有所变化、哪些已被移除。在排查第 7 步中发现的 SQL Server 专属功能时阅读。
• references/migrate-compose.md：包含带预配步骤的 docker-compose 改写前后示例。在改写 compose 文件时阅读。

保持更新

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

• Docker Compose 文件参考：关于 service、healthcheck 和 depends_on 语法的 Compose Specification。
• SqlConnection 连接字符串关键字：完整的连接字符串关键字表。

如果已配置 Microsoft Learn MCP 服务，请使用 mcp__microsoft-learn__microsoft_docs_search 或 mcp__microsoft-learn__microsoft_docs_fetch 按需获取这些资料的当前版本。此步骤为可选；如果无法使用这些工具，上述参考资料即为权威依据。