SqlPackage

SqlPackage 是命令行公用程式，藉由公開一些公用 Data-Tier Application Framework （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 Database 匯出至內部部署 SQL Server 實例，或從 SQL Server 導出至 Azure SQL Database 是資料庫可移植性的範例。 SqlPackage 透過 匯出 和 匯 入動作支援資料庫可移植性，這些動作會建立及取用 BACPAC 檔案。 SqlPackage 也透過 擷取 和 發佈 動作支援資料庫可移植性，這些動作可建立及取用 DACPAC 檔案，這些檔案可以直接包含數據或參考 儲存在 Azure Blob 記憶體中的數據。

• 匯出：將連接的 SQL 資料庫 -- 包括資料庫架構和用戶資料 - 匯出至 BACPAC 檔案 （.bacpac）。

• 匯入：將架構和數據表數據從 BACPAC 檔案匯入至新的用戶資料庫。

部署

資料庫部署是更新資料庫架構以符合所需狀態的程式，例如將數據行加入數據表或變更預存程序的內容。 SqlPackage 透過 發行 和 擷取 動作支援資料庫部署。 [發佈] 動作會更新資料庫架構，以符合來源 .dacpac 檔案的內容，而擷取動作會建立包含已連線 SQL 資料庫的架構或架構和用戶數據的數據層應用程式 （.dacpac） 檔案。 SqlPackage 通過自動創建將必要更改應用於目標資料庫的部署計劃，支援對同一專案 （.dacpac） 中的新資料庫或現有資料庫進行部署。 您可以使用 腳本 或 DeployReport 動作，先檢閱部署計劃，再將變更套用至目標資料庫。

• 抽取：建立資料層應用程式 (.dacpac) 檔案，其中包含從連接的 SQL 資料庫抽取的架構或架構和使用者資料。

• 發佈：以累加方式更新資料庫架構，以符合來源 .dacpac 檔案的架構。 如果伺服器上沒有資料庫，發行作業就會建立它。 否則，會更新現有的資料庫。

• DeployReport：建立 XML 報表，代表發佈動作將採取的變更。

• DriftReport：建立 XML 報表，代表上次註冊后套用至已註冊資料庫的變更。

• 文稿：建立 Transact-SQL 累加式更新腳本，以更新目標的架構以符合來源的架構。

Command-Line 語法

SqlPackage 會使用命令行上指定的 參數、 屬性和 SQLCMD 變數來起始指定的動作。

SqlPackage {parameters} {properties} {SQLCMD variables}

如需 SqlPackage 命令行語法的詳細資訊，請參閱 SqlPackage CLI 參考 和個別動作頁面。

實用指令

版本

將 sqlpackage 版本顯示為組建編號。 可用於互動式提示和 自動化管線。

SqlPackage /Version

幫助

您可以使用 /? 或 /help:True來顯示 SqlPackage 使用方式資訊。

SqlPackage /?

對於特定動作的專屬參數和屬性資訊，除了該動作的參數外，還應該使用 help 參數。

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

或者，您可以將服務主體 (Service Principal) 用戶端 ID 和機密傳遞至 SqlPackage 的連接字串中。 連線字串格式包含 Authentication=Active Directory Service Principal; 和 User Id=AppId; Password=<password>。 在連接字串中傳遞服務主體憑據時，該 /at 參數不是必需的，並且 SqlPackage 會在作期間根據需要刷新身份驗證。

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之後，將新用戶的密碼重設為安全值。 在自動化環境中，密碼值可以從像 Azure Key Vault 這樣的安全密鑰存放區中擷取，這是在執行 SqlPackage 之後的一個步驟。

擴充性

SqlPackage 通過 Managed Extensibility Framework （MEF） 支援擴充性， 透過稱為參與者的自定義元件支援高級方案。 這些擴展可以自定義 SqlPackage 發佈 .dacpac 檔的方式，從而允許團隊強制實施標準或自動執行特定於項目的邏輯。 部署參與者作為發佈過程的一部分，在生成部署計劃之後但在執行之前執行。 這些參與者可以使用 DeploymentPlanModifier 類物件訪問和修改部署規劃，以添加、刪除或重新排序步驟。 要開始使用部署可擴充性，請參閱 使用部署參與者自定義資料庫構建和部署。

SqlPackage 通過掃描與 SqlPackage 可執行檔相同的目錄中的動態連結庫（.dll 檔）以及通過可選命令行屬性 /p:AdditionalDeploymentContributorPaths指定的位置來發現和載入參與者程式集。 雖然這允許靈活的自定義，但它也引入了重要的安全注意事項。

這很重要

由於 SqlPackage 在執行時使用 MEF 動態載入動態連結庫（.dll 檔），因此與 SqlPackage 可執行檔一起放置的任何程式集都可以作為部署過程的一部分執行。 惡意行為者可以通過引入執行任意代碼的篡改或未經授權的擴展來利用此行為。

您有責任確保與 SqlPackage 一起使用的任何已編譯擴展檔都是安全的，並且來自受信任的來源。 我們建議控制對 SqlPackage 資料夾的訪問，並驗證所有自定義或第三方元件的完整性。

使用數據收集

SqlPackage 包含啟用因特網的功能，可收集和傳送匿名功能使用方式和診斷數據，以Microsoft。

SqlPackage 可能會收集標準計算機、使用和效能資訊，這些資訊可能會傳輸至Microsoft和分析，以改善 SqlPackage 的品質、安全性和可靠性。

SqlPackage 不會收集使用者特定或個人資訊。 為了協助大約單一用戶進行診斷，SqlPackage 會為其執行的每部計算機產生隨機 GUID，並針對它傳送的所有事件使用該值。

如需詳細資訊，請參閱 Microsoft 隱私權聲明和 SQL Server 隱私權補充。

停用遙測報告

若要停用遙測收集和報告，請將環境變數 DACFX_TELEMETRY_OPTOUT 更新為 true 或 1。

支援

DacFx 庫和 SqlPackage CLI 工具遵循 Microsoft 現代生命週期策略。 所有安全性更新、修正和新功能只會在主要版本的最新版本中發行。 將 DacFx 或 SqlPackage 安裝維護至目前版本有助於確保您能及時收到所有適用的錯誤修正。

取得 SqlPackage 的說明、提交功能要求，以及回報 DacFx GitHub 存放庫中的問題。

支援的 SQL 供應項目

SqlPackage 和 DacFx 在 SqlPackage/DacFx 版本中支援所有 支援的 SQL 版本 。 例如，2022 年 1 月 14 日 SqlPackage 版本支援 2022 年 1 月 14 日所有支援的 SQL 版本。 如需 SQL 支援原則的詳細資訊，請參閱 SQL 支持原則。

除了 SQL Server 之外，SqlPackage 和 DacFx 還支援 Azure SQL 受控執行個體、Azure SQL 資料庫、Azure Synapse Analytics 和 Fabric Data Warehouse。

後續步驟

• 深入了解 SqlPackage 匯出
• 深入瞭解 SqlPackage 發佈。
• 進一步瞭解 SqlPackage 導出
• 深入瞭解 SqlPackage 匯入
• 深入瞭解 與 SqlPackage 相關問題的疑難排解
• 在 DacFx GitHub 存放庫 中分享 SqlPackage 的意見反應