mcpField
A
azuresql-db-import

azuresql-db-import

github.com/microsoft数据与数据库2274 次安装1 周前更新
代码仓库

关于 azuresql-db-import

此技能介绍如何将现有数据库导入本地 Azure SQL Database 容器，适用于需要迁移数据与架构或仅迁移架构的开发者。它使用 SqlPackage 处理 `.bacpac` 或 `.dacpac`，并说明导入前创建数据库及导入后验证。

主要功能

  1. 01从 `.bacpac` 导入架构和数据
  2. 02发布 `.dacpac` 中的架构
  3. 03导入前创建目标数据库
  4. 04验证引擎身份和导入对象
  5. 05检查 PaaS 限制导致跳过的对象

适用场景

  1. 01将数据库导出包导入本地容器
  2. 02向本地数据库发布仅含架构的包
  3. 03迁移后检查表和行数

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/microsoft/azure-sql-database-container --skill azuresql-db-import

安装后在 Claude Code 中输入/azuresql-db-import确认已加载。

附带文件references/sqlpackage-import.mdskill.spec.jsonc

详细介绍

Azure SQL Database 容器：导入数据库

使用 SqlPackage，从 .bacpac（架构 + 数据）或 .dacpac（仅架构）将现有数据库导入本地容器。

已于 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、RESTORE 返回 Msg 40510，以及 SqlPackage 在主机上运行，因为该映像未包含它。

这是什么（关键事实）

这是在本地运行的 Azure SQL Database 引擎（Private Preview）： SELECT SERVERPROPERTY('EngineEdition') 返回 5，Edition 返回 'SQL Azure'。它不是 SQL Server 映像 mcr.microsoft.com/mssql/server。如果你正准备使用该 SQL Server 映像，请停下并改用此映像。

  • 映像：sqldbpreview-dpgaeqhmgphzd4bk.azurecr.io/azure-sql/db-dev:latest （x64、linux/amd64；私有预览版注册表，请先登录）。在 Private Preview 期间，注册表和标记为临时配置。
  • 在非 x64 主机上，添加 --platform linux/amd64。
  • 引擎不会自动创建数据库。导入前，必须在连接到 master 的会话中执行 CREATE DATABASE appdb。
  • 没有还原途径。 在所有会话中，BACKUP 和 RESTORE 均会被拒绝并返回 Msg 40510，这与云中的 Azure SQL Database 完全一致，因此无论 .bak 文件被复制到何处，都无法通过它导入。使用 SqlPackage 配合 bacpac 或 dacpac 才是导入途径，本技能余下部分将介绍此方法。
  • 避免使用 USE 切换数据库。在用户数据库会话中（也就是符合 Azure 行为的开发环境），USE 会返回 Msg 40508，这与云中的 Azure SQL Database 完全一致。master 连接是一个不强制执行 Azure 语句筛选器的配置会话，因此在那里 USE 看起来可以正常工作；但 master 仅用于配置，不用于应用程序工作。始终在连接字符串中选择目标数据库（Database=appdb，或 sqlcmd 使用 -d appdb）。

如需了解容器详情（启动步骤、连接模型、就绪状态），请参阅 azuresql-db-container 技能。下方列出了所需的最少内容。

三个步骤

  1. 启动容器，并在 master 中配置目标数据库。
  2. 运行 SqlPackage /Action:Import，目标指向已配置的用户数据库。
  3. 验证导入结果（PaaS 限制可能会导致部分对象被丢弃）。

这是 Private Preview 支持的导入途径。务必验证结果。

步骤 0：启动容器并配置目标数据库

使用规范的启动步骤。它会选择一个空闲主机端口，仅在非 x64 主机上添加 --platform，通过重试循环等待就绪，并在同一循环中于 master 上配置目标数据库 appdb。

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

如果容器已经在运行，只需在 master 上配置目标数据库：

docker exec sqldb /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;"

导入前，目标数据库必须已存在且为空。SqlPackage 会导入用户数据库；在这里，它不会替你在服务器上创建数据库。

步骤 1：使用 SqlPackage 导入

将 /TargetConnectionString 指向已配置的数据库（Database=appdb）。 使用规范的连接字符串格式：User Id=/Password=/Database=， TrustServerCertificate=true。

架构 + 数据（.bacpac）：

SqlPackage /Action:Import \
  /SourceFile:"./mydatabase.bacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

仅架构（.dacpac）使用 /Action:Publish，而不是 Import：

SqlPackage /Action:Publish \
  /SourceFile:"./myschema.dacpac" \
  /TargetConnectionString:"Server=localhost,$HOST_PORT;Database=appdb;User Id=sa;Password=$MSSQL_SA_PASSWORD;TrustServerCertificate=true"

如果本地未安装 SqlPackage，请参阅 references/sqlpackage-import.md，了解安装选项和基于容器的备用方案。

步骤 2：验证

确认引擎标识，并抽查对象是否已导入：

docker exec sqldb /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "$MSSQL_SA_PASSWORD" -C -b -d appdb \
  -Q "SELECT SERVERPROPERTY('EngineEdition') AS EngineEdition; SELECT COUNT(*) AS Tables FROM sys.tables;"

EngineEdition 必须为 5。然后，将几张关键表的行数与源数据库进行核对。

可能无法迁移的内容（PaaS 限制）

此引擎为 Azure SQL Database（Engine Edition 5），因此 Azure SQL DB 不支持的 SQL Server 功能在导入时会失败或被跳过：

  • 跨数据库的三段式名称引用和大多数跨数据库查询。
  • 脚本中的 USE <db>：用户数据库会话会返回 Msg 40508。请在连接字符串中选择目标数据库（Database=appdb，或 -d appdb）。
  • 服务器范围的对象：SQL Agent 作业、服务器级登录名／链接服务器、filestream、某些 CLR 设置以及文件组／物理文件设置。
  • 实例级 DATABASE_DEFAULT 排序规则假设，以及不支持的兼容性级别功能。

请查看 SqlPackage 输出，了解被跳过或阻止的项目。常见错误模式及修复方法，请参阅 references/sqlpackage-import.md。

验证规则

  • 导入前，目标数据库必须已在 master 上创建且为空。
  • /TargetConnectionString 设置为 Database=appdb（绝不能使用字面值 master）。
  • 导入后，目标上的 SERVERPROPERTY('EngineEdition') 为 5。
  • 使用 .bacpac 通过 /Action:Import 导入架构和数据；使用 .dacpac 通过 /Action:Publish 发布架构。
  • 如果上述任何验证规则未通过，或你必须偏离此技能才能完成任务，则此技能存在问题：加载 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 SQL Server 镜像。
  • 请勿尝试使用 RESTORE DATABASE ... FROM DISK；它会因 Msg 40510 被拒绝，而且将 .bak 复制到容器中也无法改变这一点。
  • 请勿导入到 master；请导入到已预配的用户数据库。
  • 请勿在任何预处理／后处理脚本中使用 USE appdb；请改为在连接字符串中选择数据库。
  • 请勿依赖 /docker-entrypoint-initdb.d/*.sql 自动填充数据；此镜像不会执行这些脚本。
  • 请勿将非 x64 主机称为“受支持”；在非 x64 主机上只需添加 --platform linux/amd64。
  • 请勿将成功执行 docker run 视为“已就绪”；请在重试循环中进行预配。

参考资料

  • references/sqlpackage-import.md：SqlPackage 安装、完整标志参考、基于容器的备用方案，以及常见导入错误和修复方法。缺少 SqlPackage 或导入失败时请阅读。

保持最新

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

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

评论

支持 Markdown