SqlPackage

  • 發行項

SqlPackage 是一個命令列公用程式，它會公開部分公用 Data-Tier Application Framework (DacFx) API，讓資料庫開發工作自動化。 SqlPackage 的主要使用案例著重於 SQL Server、Azure SQL 和 Azure Synapse Analytics 資料庫系列的資料庫可攜性和部署。 可以使用 Azure Pipelines 和 GitHub Actions 或其他 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 檔案的內容，而 [擷取] 動作會建立包含已連線 SQL 資料庫的結構描述和使用者資料的資料層應用程式 (.dacpac) 檔案。 SqlPackage 會自動建立將必要變更套用至目標資料庫的部署計劃，以針對相同成品 (.dacpac) 的新資料庫或現有資料庫進行部署。 可以使用 Script 或 DeployReport 動作，先檢閱部署計劃，再將變更套用至目標資料庫。

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

  • Publish：以累加方式更新資料庫結構描述，以符合來源 .dacpac 檔案的結構描述。 如果資料庫不存在伺服器上，發行作業會加以建立。 否則，將更新現有的資料庫。

  • DeployReport：建立 XML 報告，表示發佈動作將進行的變更。

  • DriftReport：建立 XML 報告，表示自上次註冊以來套用於已註冊資料庫的變更。

  • Script：建立 Transact-SQL 累加更新指令碼，這個指令碼會更新目標的結構描述以符合來源的結構描述。

命令列語法

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 Actions 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 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 之後，將新使用者的密碼重設為安全值。 在自動化環境中，可以在 SqlPackage 後續的步驟中，從安全金鑰存放區 (例如 Azure Key Vault) 擷取密碼值。

使用量資料收集

SqlPackage 包含啟用網際網路的功能，可收集匿名的功能使用情況和診斷資料，並傳送給 Microsoft。

SqlPackage 可能會收集標準電腦、使用情況與效能資訊，這些資訊可能會傳輸至 Microsoft 並加以分析，以改善 SqlPackage 的品質、安全性與可靠性。

SqlPackage 不會收集使用者特定的或個人資訊。 為了協助估計單一使用者進行診斷，SqlPackage 會為其執行的每部電腦產生一個隨機 GUID，並將該值用於其傳送的所有事件。

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

停用遙測報告

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

支援

DacFx 程式庫和 SqlPackage CLI 工具已採用 Microsoft 新式生命週期原則。 只有在主要版本的最新點版本中，才會發行所有安全性更新、修正程式和新功能。 將 DacFx 或 SqlPackage 安裝維持在目前版本，有助於確保您能及時收到所有適用的錯誤修正。

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

支援的 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。

下一步