SqlPackage

SqlPackage 是一个命令行实用工具，它通过公开一些公共 Data-Tier 应用程序框架 （DacFx） API 来自动执行数据库开发任务。 SqlPackage 的主要用例侧重于 SQL Server、Azure SQL 和 Azure Synapse Analytics 系列数据库的数据库可移植性和部署。 SqlPackage 可以使用 Azure Pipelines 和 GitHub Actions 或其他 CI/CD 工具实现自动化。

下载最新版本。 有关最新版本的详细信息，请参阅发行说明。

可移植性

数据库可移植性是能够在 SQL Server、Azure SQL 和 Azure Synapse Analytics 的不同实例之间移动数据库架构和数据。 将数据库从 Azure SQL 数据库导出到本地 SQL Server 实例或从 SQL Server 导出到 Azure SQL 数据库是数据库可移植性的示例。 SqlPackage 通过 导出 和 导入 操作支持数据库的可移植性，这些操作创建和使用 BACPAC 文件。 SqlPackage 还支持通过 提取 和 发布 作（创建和使用 DACPAC 文件）实现数据库可移植性，这些文件可以直接包含数据或引用 存储在 Azure Blob 存储中的数据。

• 导出：将连接的 SQL 数据库（包括数据库架构和用户数据）导出到 BACPAC 文件（.bacpac）。

• 导入：将架构和表数据从 BACPAC 文件导入到新的用户数据库中。

部署

数据库部署是更新数据库架构以匹配所需状态的过程，例如向表添加列或更改存储过程的内容。 SqlPackage 通过发布和提取操作支持数据库部署。 发布作将更新数据库架构以匹配源 .dacpac 文件的内容，而提取作会创建一个数据层应用程序 （.dacpac） 文件，其中包含连接的 SQL 数据库中的架构或架构和用户数据。 SqlPackage 通过自动创建部署计划，将必要的更改应用于目标数据库，从而实现从同一工件 (.dacpac) 中部署到新数据库或现有数据库。 可以在将更改应用到目标数据库之前，使用 脚本 或 DeployReport 操作查看部署计划。

• 提取：创建数据层应用程序 (.dacpac) 文件，该文件包含连接的 SQL 数据库中的架构数据或是架构和用户数据。

• 发布：以增量方式更新数据库架构以匹配源 .dacpac 文件的架构。 如果服务器上不存在数据库，发布作会创建它。 否则，将更新现有数据库。

• DeployReport：创建一个 XML 报表，表示发布作将采取的更改。

• DriftReport：创建一个 XML 报表，表示自上次注册以来应用于已注册数据库的更改。

• 脚本：创建一个 Transact-SQL 增量更新脚本，用于更新目标的架构以匹配源的架构。

命令行语法

SqlPackage 使用命令行中指定的 参数、 属性和 SQLCMD 变量启动指定的作。

SqlPackage {parameters} {properties} {SQLCMD variables}

有关 SqlPackage 命令行语法的详细信息，请参阅 SqlPackage CLI 参考 和单个作页。

实用工具命令

版本

将 sqlpackage 版本显示为生成号。 可用于交互式提示和 自动化管道。

SqlPackage /Version

帮助

可以使用 /? 或 /help:True来显示 SqlPackage 使用情况信息。

SqlPackage /?

对于特定操作的特定参数和属性信息，除了使用该操作的参数之外，还要使用帮助参数。

SqlPackage /Action:Publish /?

身份验证

SqlPackage 使用 SqlClient 中提供的方法进行身份验证。 可以通过每个 SqlPackage 操作的连接字符串参数（/SourceConnectionString 和 /TargetConnectionString），或通过连接属性的各个参数来完成身份验证类型的配置。 连接字符串支持以下身份验证方法：

• SQL Server 身份验证
• Active Directory （Windows） 身份验证
• Microsoft Entra 身份验证
  • 用户名/密码
  • 集成身份验证
  • 通用身份验证
  • 托管标识
  • 服务主体

托管标识

在自动化环境中， Microsoft Entra 托管标识 是推荐的身份验证方法。 此方法不需要在运行时将凭据传递给 SqlPackage，因为 SqlPackage 使用托管标识连接到支持 Microsoft Entra 身份验证的数据库，并获取Microsoft Entra 令牌，而无需管理凭据。 当为运行 SqlPackage 操作的环境配置托管标识时，SqlPackage 操作可以使用该标识向 Azure SQL 进行身份验证。 有关为环境配置托管标识的详细信息，请参阅 托管标识文档。

使用系统分配的托管标识的示例连接字符串是：

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Azure DevOps 和 GitHub Actions CI/CD 管道都支持托管标识。

服务主体

Microsoft Entra 应用程序服务主体是 Microsoft Entra 应用程序中的安全对象，用于定义应用程序在给定租户中可以执行的操作。 它们在应用程序注册过程中在 Azure 门户中设置，并配置为访问 Azure 资源，例如 Azure SQL。 有关为环境配置服务主体的详细信息，请参阅 服务主体文档。

将 SqlPackage 与服务主体配合使用时，可以检索访问令牌并将其传递给 SqlPackage。 可以使用 Azure PowerShell 模块 或 Azure CLI 检索访问令牌。 在此过程中，调用系统可保持对令牌刷新或失效的控制。 可以使用/at参数将访问令牌传递给SqlPackage。

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

或者，可以在连接字符串中将服务主体客户端 ID 和机密传递给 SqlPackage。 连接字符串格式包括Authentication=Active Directory Service Principal;和 User Id=AppId; Password=<password>。 在连接字符串中传递服务主体凭据时，/at 参数不是必需的，SqlPackage 会在操作期间根据需要刷新身份验证。

Azure DevOps 和 GitHub Actions CI/CD 管道均支持服务主体。

环境变量

连接池

可以通过将 CONNECTION_POOLING_ENABLED 环境变量设置为 True，为 SqlPackage 建立的所有连接启用连接池。 对于需要使用 Microsoft Entra 用户名和密码连接的操作，建议使用此设置，以避免 Microsoft 身份验证库 (MSAL) 的限制。

临时文件

在 SqlPackage 操作期间，表数据会在压缩之前或解压缩之后写入到临时文件中。 对于大型数据库，这些临时文件可能会占用大量磁盘空间，但可以指定其位置。 导出和提取作包括一个可选属性，用于指定 /p:TempDirectoryForTableData 以替代 SqlPackage 的默认值。

.NET API GetTempPath 用于确定 SqlPackage 中的默认值。

对于 Windows，将按以下顺序检查环境变量，并使用第一个存在的路径：

1. 环境变量指定的 TMP 路径。
2. 环境变量指定的 TEMP 路径。
3. 环境变量指定的 USERPROFILE 路径。
4. Windows 目录。

对于 Linux 和 macOS，如果未在 TMPDIR 环境变量中指定路径，则使用默认路径 /tmp/ 。

SqlPackage 和数据库用户

包含的数据库用户包括在 SqlPackage 操作中。 但是，定义的密码部分由 SqlPackage 设置为随机生成的字符串，现有值不会传输。 建议在导入 .bacpac 或部署 .dacpac后，新用户的密码重置为安全值。 在自动化环境中，可以从 Azure Key Vault 等安全密钥存储中检索密码值，这个步骤是在 SqlPackage 之后。

可扩展性

SqlPackage 通过 托管扩展性框架（MEF）支持扩展性，通过称为 参与者的自定义组件启用高级方案。 这些扩展可以自定义 SqlPackage 如何发布 .dacpac 文件，从而允许团队强制实施标准或自动执行特定于项目的逻辑。 部署参与者在生成部署计划之后，但在执行该计划之前，作为发布过程的一部分执行。 这些参与者可以使用类对象访问和修改部署计划 DeploymentPlanModifier ，以添加、删除或重新排序步骤。 若要开始使用部署扩展性，请参阅 使用部署参与者自定义数据库生成和部署。

SqlPackage 通过扫描 SqlPackage 可执行文件所在的目录中的动态链接库（.dll 文件）以及通过可选命令行属性 /p:AdditionalDeploymentContributorPaths指定的位置来发现和加载参与者程序集。 虽然这允许灵活的自定义，但它也引入了重要的安全注意事项。

使用情况数据收集

SqlPackage 包含支持联网的功能，这些功能可以收集并将匿名功能使用情况和诊断数据发送给 Microsoft。

SqlPackage 可能会收集标准计算机、使用情况和性能信息，这些信息可以传输到Microsoft和分析，以提高 SqlPackage 的质量、安全性和可靠性。

SqlPackage 不会收集用户特定或个人信息。 为了协助模拟单个用户进行诊断，SqlPackage 会为其运行的每台计算机生成一个随机 GUID，并使用该值用于其发送的所有事件。

有关详细信息，请参阅 Microsoft 隐私声明和 SQL Server 隐私补充。

禁用遥测报告

若要禁用遥测收集和报告，请将环境变量 DACFX_TELEMETRY_OPTOUT 更新为 true 或 1更新。

支持

DacFx 库和 SqlPackage CLI 工具遵循 Microsoft新式生命周期策略。 所有安全更新、修复和新功能将仅在主要版本的最新小版本中发布。 将 DacFx 或 SqlPackage 安装维护到当前版本有助于确保及时收到所有适用的 bug 修复。

获取有关 SqlPackage、提交功能请求和在 DacFx GitHub 存储库中报告问题的帮助。

支持的 SQL 产品/服务

SqlPackage 和 DacFx 在 SqlPackage/DacFx 版本时支持所有 受支持的 SQL 版本 。 例如，2022 年 1 月 14 日 SqlPackage 版本支持 2022 年 1 月 14 日支持的所有 SQL 版本。 有关 SQL 支持策略的详细信息，请参阅 SQL 支持策略。

除了 SQL Server，SqlPackage 和 DacFx 还支持 Microsoft Fabric 中的 Azure SQL 托管实例、Azure SQL 数据库、Azure Synapse Analytics 和 Synapse 数据仓库。

后续步骤

• 了解有关 SqlPackage 提取的详细信息
• 了解有关 SqlPackage 发布的详细信息
• 了解有关 SqlPackage 导出的详细信息
• 详细了解如何使用 SqlPackage 导入
• 详细了解如何 对 SqlPackage 进行故障排除
• 在 DacFx GitHub 存储库中共享有关 SqlPackage 的反馈