SqlPackage

SqlPackage är ett kommandoradsverktyg som automatiserar databasutvecklingsuppgifterna genom att exponera några av api:erna för offentliga Data-Tier Application Framework (DacFx). De primära användningsfallen för SqlPackage fokuserar på databasportabilitet och distributioner för SQL Server, Azure SQL och Azure Synapse Analytics-serien med databaser. SqlPackage kan automatiseras med Azure Pipelines och GitHub-åtgärder eller andra CI/CD-verktyg.

Ladda ned den senaste versionen. Mer information om den senaste versionen finns i versionsanteckningar.

Portabilitet

Databasportabilitet är möjligheten att flytta ett databasschema och data mellan olika instanser av SQL Server, Azure SQL och Azure Synapse Analytics. Att exportera en databas från Azure SQL Database till en lokal SQL Server-instans, eller från SQL Server till Azure SQL Database, är exempel på databasportabilitet. SqlPackage stöder databasportabilitet via åtgärderna Export och Import , som skapar och använder BACPAC-filer. SqlPackage stöder också databasportabilitet via åtgärderna Extrahera och publicera , som skapar och använder DACPAC-filer, som antingen kan innehålla data direkt eller referensdata som lagras i Azure Blob Storage.

• Exportera: Exporterar en ansluten SQL-databas – inklusive databasschema och användardata – till en BACPAC-fil (.bacpac).

• Importera: Importerar schema- och tabelldata från en BACPAC-fil till en ny användardatabas.

Utrullningar

Databasdistributioner är processen att uppdatera ett databasschema för att matcha ett önskat tillstånd, till exempel att lägga till kolumner i en tabell eller ändra innehållet i en lagrad procedur. SqlPackage stöder databasdistributioner via åtgärderna Publicera och extrahera . Åtgärden Publicera uppdaterar ett databasschema så att det matchar innehållet i en .dacpac-källfil, medan åtgärden Extrahera skapar en datanivåfil (.dacpac) som innehåller schemat eller schemat och användardata från en ansluten SQL-databas. SqlPackage möjliggör distributioner mot både nya eller befintliga databaser från samma artefakt (.dacpac) genom att automatiskt skapa en distributionsplan som tillämpar nödvändiga ändringar på måldatabasen. Distributionsplanen kan granskas innan du tillämpar ändringarna på måldatabasen med åtgärderna Skript eller DeployReport .

• Extrahera: Skapar en fil för datanivåprogram (.dacpac) som innehåller schema eller schema och användardata från en ansluten SQL-databas.

• Publicera: Uppdaterar inkrementellt ett databasschema så att det matchar schemat för en .dacpac-källfil. Om databasen inte finns på servern skapar publiceringsåtgärden den. Annars uppdateras en befintlig databas.

• DeployReport: Skapar en XML-rapport som representerar de ändringar som en publiceringsåtgärd skulle göra.

• DriftReport: Skapar en XML-rapport som representerar de ändringar som tillämpats på en registrerad databas sedan den senast registrerades.

• Script: Skapar ett Transact-SQL inkrementellt uppdateringsskript som uppdaterar schemat för ett mål så att det matchar schemat för en källa.

Command-Line syntax

SqlPackage initierar de åtgärder som anges med hjälp av de parametrar, egenskaper och SQLCMD-variabler som anges på kommandoraden.

SqlPackage {parameters} {properties} {SQLCMD variables}

Mer information om sqlPackage-kommandoradssyntaxen finns i SqlPackage CLI-referensen och enskilda åtgärdssidor.

Verktygskommandon

Utgåva

Visar sqlpackage-versionen som ett versionsnummer. Kan användas i interaktiva uppmaningar och i automatiserade pipelines.

SqlPackage /Version

Hjälp

Du kan visa användningsinformation för SqlPackage med hjälp av /? eller /help:True.

SqlPackage /?

För parameter- och egenskapsinformation som är specifik för en viss åtgärd använder du hjälpparametern utöver den åtgärdens parameter.

SqlPackage /Action:Publish /?

Autentisering

SqlPackage autentiserar med metoder som är tillgängliga i SqlClient. Du kan konfigurera autentiseringstypen via anslutningssträngsparametrarna för varje SqlPackage-åtgärd (/SourceConnectionString och /TargetConnectionString) eller via enskilda parametrar för anslutningsegenskaper. Följande autentiseringsmetoder stöds i en anslutningssträng:

• SQL Server-autentisering
• Active Directory-autentisering (Windows)
• Microsoft Entra-autentisering
  • Användarnamn/lösenord
  • Integrerad autentisering
  • Universell autentisering
  • Hanterad identitet
  • Service Principal

Hanterad identitet

I automatiserade miljöer är Microsoft Entra-hanterad identitet den rekommenderade autentiseringsmetoden. Den här metoden kräver inte att autentiseringsuppgifter skickas till SqlPackage vid körning eftersom SqlPackage använder hanterade identiteter för att ansluta till databaser som stöder Microsoft Entra-autentisering och för att hämta Microsoft Entra-token, utan hantering av autentiseringsuppgifter. När den hanterade identiteten har konfigurerats för miljön där SqlPackage-åtgärden körs kan SqlPackage-åtgärden använda den identiteten för att autentisera till Azure SQL. Mer information om hur du konfigurerar en hanterad identitet för din miljö finns i dokumentationen om hanterad identitet.

Ett exempel på en anslutningssträng med systemtilldelad hanterad identitet är:

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

Hanterade identiteter stöds i både Azure DevOps - och GitHub actions CI/CD-pipelines.

Service Principal

Microsoft Entra-programtjänstens huvudprincipaler är säkerhetsobjekt inom ett Microsoft Entra-program som definierar vad ett program kan göra i en given klientorganisation. De konfigureras i Azure-portalen under programregistreringsprocessen och konfigureras för åtkomst till Azure-resurser, till exempel Azure SQL. Mer information om hur du konfigurerar ett huvudnamn för tjänsten för din miljö finns i dokumentationen för tjänstens huvudnamn.

När du använder SqlPackage med tjänstens huvudnamn kan du hämta en åtkomsttoken och skicka den till SqlPackage. Åtkomsttoken kan hämtas med hjälp av Azure PowerShell-modulen eller Azure CLI. I den här processen behåller det anropande systemet kontroll över tokenuppdatering eller ogiltighet. Åtkomsttoken kan skickas till SqlPackage med hjälp av parametern /at .

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

Alternativt kan du skicka tjänstens huvudklient-ID och lösenord till SqlPackage i anslutningssträngen. Anslutningssträngformatet innehåller Authentication=Active Directory Service Principal; och User Id=AppId; Password=<password>. När autentiseringsuppgifterna för tjänstens huvudnamn skickas i anslutningssträngen /at krävs inte parametern och SqlPackage uppdaterar autentiseringen efter behov under åtgärden.

Tjänstansvariga stöds i både Azure DevOps och GitHub Actions CI/CD-pipelines.

Miljövariabler

Anslutningspoolning

Anslutningspooler kan aktiveras för alla anslutningar som görs av SqlPackage genom att miljövariabeln anges CONNECTION_POOLING_ENABLED till True. Den här inställningen rekommenderas för operationer som involverar Microsoft Entra-anslutningar med användarnamn och lösenord, för att undvika begränsningar av Microsoft Authentication Library (MSAL).

Tillfälliga filer

Under SqlPackage-åtgärder skrivs tabelldata till temporära filer före komprimering eller efter dekomprimering. För stora databaser kan dessa temporära filer ta upp en betydande mängd diskutrymme, men deras plats kan anges. Export- och extraheringsåtgärderna innehåller en valfri egenskap som du kan ange /p:TempDirectoryForTableData för att åsidosätta SqlPackages standardvärde.

.NET API GetTempPath används för att fastställa standardvärdet i SqlPackage.

För Windows kontrolleras följande miljövariabler i följande ordning och den första sökvägen som finns används:

1. Sökvägen som anges av TMP miljövariabeln.
2. Sökvägen som anges av TEMP miljövariabeln.
3. Sökvägen som anges av USERPROFILE miljövariabeln.
4. Windows-katalogen.

För Linux och macOS används standardsökvägen TMPDIR om sökvägen inte anges i /tmp/ miljövariabeln.

SqlPackage- och databasanvändare

Inneslutna databasanvändare ingår i SqlPackage-åtgärder. Lösenordsdelen av definitionen är dock inställd på en slumpmässigt genererad sträng av SqlPackage, det befintliga värdet överförs inte. Vi rekommenderar att den nya användarens lösenord återställs till ett säkert värde efter importen av en .bacpac eller distributionen av en .dacpac. I en automatiserad miljö kan lösenordsvärden hämtas från ett säkert nyckelarkiv, till exempel Azure Key Vault, i ett steg efter SqlPackage.

Utökningsbarhet

SqlPackage stöder utökningsbarhet via MEF (Managed Extensibility Framework), vilket möjliggör avancerade scenarier via anpassade komponenter som kallas deltagare. Dessa tillägg kan anpassa hur SqlPackage publicerar .dacpac filer, vilket gör det möjligt för team att tillämpa standarder eller automatisera projektspecifik logik. Distributionsdeltagare körs som en del av publiceringsprocessen, efter att distributionsplanen har genererats men innan den körs. Dessa deltagare kan komma åt och ändra distributionsplanen med hjälp av ett DeploymentPlanModifier klassobjekt för att lägga till, ta bort eller ändra ordning på steg. Information om hur du kommer igång med utökningsbarhet för distribution finns i Använda distributionsdeltagare för att anpassa databasbygge och distribution.

SqlPackage identifierar och läser in deltagarsammansättningar genom att söka efter dynamiska länkbibliotek (.dll filer) i samma katalog som den körbara SqlPackage-filen samt de platser som anges via valfri kommandoradsegenskap /p:AdditionalDeploymentContributorPaths. Även om detta möjliggör flexibel anpassning, introducerar det också viktiga säkerhetsöverväganden.

Insamling av användningsdata

SqlPackage innehåller Internetaktiverade funktioner som kan samla in och skicka anonym funktionsanvändning och diagnostikdata till Microsoft.

SqlPackage kan samla in standardinformation om dator, användning och prestanda som kan överföras till Microsoft och analyseras för att förbättra kvaliteten, säkerheten och tillförlitligheten i SqlPackage.

SqlPackage samlar inte in användarspecifik eller personlig information. För att hjälpa till att approximera en enskild användare för diagnostiska ändamål genererar SqlPackage ett slumpmässigt GUID för varje dator som körs på och använder det värdet för alla händelser som den skickar.

Mer information finns i Microsofts sekretesspolicy och SQL Server-sekretesstillägget.

Avaktivera telemetrirapportering

Om du vill inaktivera insamling och rapportering av telemetri uppdaterar du miljövariabeln DACFX_TELEMETRY_OPTOUT till true eller 1.

Stöd

DacFx-biblioteket och SqlPackage CLI-verktyget följer Microsofts moderna livscykelpolicy. Alla säkerhetsuppdateringar, korrigeringar och nya funktioner släpps endast i den senaste punktversionen av huvudversionen. Genom att underhålla dina DacFx- eller SqlPackage-installationer till den aktuella versionen ser du till att du får alla tillämpliga felkorrigeringar i tid.

Få hjälp med SqlPackage, skicka funktionsbegäranden och rapportera problem på DacFx GitHub-lagringsplatsen.

SQL-erbjudanden som stöds

SqlPackage och DacFx stöder alla SQL-versioner som stöds vid tidpunkten för SqlPackage/DacFx-versionen. Till exempel stöder en SqlPackage-version den 14 januari 2022 alla versioner av SQL som stöds i januari 14 2022. Mer information om SQL-supportprinciper finns i SQL-supportprincipen.

Förutom SQL Server stöder SqlPackage och DacFx Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics och Fabric Data Warehouse.

Nästa steg

• Läs mer om SqlPackage Extract
• Läs mer om SqlPackage Publish
• Läs mer om SqlPackage Export
• Läs mer om SqlPackage Import
• Läs mer om felsökningsproblem med SqlPackage
• Dela feedback om SqlPackage på DacFx GitHub-lagringsplatsen