通过

SqlPackage

  • 项目

SqlPackage 是一种命令行实用工具，通过公开一些公共数据层应用程序框架 (DacFx) API 自动执行数据库开发任务。 SqlPackage 的主要用例侧重于 SQL Server、Azure SQL 和 Azure Synapse Analytics 系列数据库的数据库可移植性和部署。 可以使用 Azure Pipelines 和 GitHub 操作或其他 CI/CD 工具自动执行 SqlPackage。

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

注意

虽然 Microsoft Entra ID 是 Azure Active Directory (Azure AD) 的新名称，但为了防止中断现有环境，Azure AD 仍保留在一些硬编码的元素中，例如 UI 字段、连接提供程序、错误代码和 cmdlet。 在本文中，这两个名称可以互换。

便携性

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

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

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

部署

数据库部署是更新数据库架构以匹配所需状态的过程，例如向表添加列或更改存储过程的内容。 SqlPackage 通过发布和提取操作支持数据库部署。 发布操作将更新数据库架构以匹配源 .dacpac 文件的内容，而提取操作则会创建一个数据层应用程序 (.dacpac) 文件，其中包含连接的 SQL 数据库中的架构或架构和用户数据。 SqlPackage 通过自动创建将必要更改应用于目标数据库的部署计划，从而针对同一项目 (.dacpac) 中的新数据库或现有数据库启用部署。 可以使用 Script 或 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 ID 以前称为 Azure Active Directory (Azure AD)。

在自动化环境中，建议使用的身份验证方法是 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 操作 CI/CD 管道都支持托管标识。

服务主体

注意

Microsoft Entra ID 以前称为 Azure Active Directory (Azure AD)。

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

Azure DevOps 和 GitHub 操作 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 后，将新用户的密码重置为安全值。 在自动化环境中，可在 SqlPackage 后面的步骤中从安全密钥存储（如 Azure Key Vault）检索密码值。

使用情况数据收集

SqlPackage 包含已启用 Internet 的功能，这些功能可收集匿名功能使用情况和诊断数据并将其发送给 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 Data Warehouse。

后续步骤