SqlPackage

  • 项目

SqlPackage 是一种命令行实用工具，通过公开一些公共数据层应用程序框架 (DacFx) API 自动执行以下数据库开发任务：

  • 版本：返回 SqlPackage 应用程序的生成号。

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

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

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

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

  • DeployReport：创建表示发布操作将进行的更改的 XML 报表。

  • DriftReport：创建表示自注册数据库注册以来对其应用的更改的 XML 报表。

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

通过 SqlPackage 命令行工具，可以指定这些操作以及特定于操作的参数和属性。

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

注意

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

命令行语法

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

SqlPackage {parameters} {properties} {SQLCMD variables}

退出代码

SqlPackage 命令将返回以下退出代码：

  • 0 = 成功
  • 非零 = 失败

用例

各个操作页上提供了更多示例。

创建当前数据库架构的 .dacpac 文件：

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

参数

某些参数在 SqlPackage 操作之间共享。 下面是汇总参数的表，如需详细信息，请单击特定操作页。

参数 缩写 提取 发布 导出 导入 DeployReport DriftReport 脚本
/AccessToken: /at x X X X X X x
/ClientId: /cid x
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x X X X X X x
/DiagnosticsFile: /df x X X X X X x
/MaxParallelism: /mp x X X X X X x
/OutputPath: /op x X x
/OverwriteFiles: /of x X X X X x
/Profile: /pr x X x
/Properties: /p x X X X X x
/Quiet: /q x X X X X X x
/Secret: /secr x
/SourceConnectionString: /scs x X X X x
/SourceDatabaseName: /sdn x X X X x
/SourceEncryptConnection: /sec x X X X x
/SourceFile: /sf x X X x
/SourcePassword: /sp x X X X x
/SourceServerName: /ssn x X X X x
/SourceTimeout: /st x X X X x
/SourceTrustServerCertificate: /stsc x X X X x
/SourceUser: /su x X X X x
/TargetConnectionString: /tcs x X X x
/TargetDatabaseName: /tdn x X X X x
/TargetEncryptConnection: /tec x X X X x
/TargetFile: /tf x X X x
/TargetPassword: /tp x X X X x
/TargetServerName: /tsn x X X X x
/TargetTimeout: /tt x X X X x
/TargetTrustServerCertificate: /ttsc x X X X x
/TargetUser: /tu x X X X x
/TenantId: /tid x X X X X X x
/UniversalAuthentication: /ua x X X X X X x
/Variables: /v x x

属性

SqlPackage 操作支持大量属性来修改操作的默认行为。 有关详细信息，请单击特定操作页。

实用工具命令

版本

将 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 操作的环境配置托管标识时，SqlPackage 操作可以使用该标识针对 Azure SQL 进行身份验证。 有关为环境配置托管标识的更多信息，请参阅托管标识文档。

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

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

环境变量

连接池

可以通过将 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 支持策略。

后续步骤