Delen via

SqlPackage

  • Artikel

SqlPackage is een opdrachtregelprogramma waarmee de databaseontwikkelingstaken worden geautomatiseerd door enkele van de openbare Data-Tier DacFx-API's (Application Framework) beschikbaar te maken. De primaire use cases voor SqlPackage richten zich op databaseportabiliteit en implementaties voor de SQL Server-, Azure SQL- en Azure Synapse Analytics-familie van databases. SqlPackage kan worden geautomatiseerd met behulp van Azure Pipelines en GitHub-acties of andere CI/CD-hulpprogramma's.

Download de nieuwste versie. Zie voor meer informatie over de nieuwste release de releaseopmerkingen.

Opmerking

Hoewel Microsoft Entra ID de nieuwe naam is voor Azure Active Directory (Azure AD), blijft Azure AD, om verstoring van bestaande omgevingen te voorkomen, nog steeds bestaan in sommige hardcoded elementen, zoals UI-velden, verbindingsproviders, foutcodes en cmdlets. In dit artikel zijn de twee namen uitwisselbaar.

Draagbaarheid

Databaseportabiliteit is de mogelijkheid om een databaseschema en gegevens te verplaatsen tussen verschillende exemplaren van SQL Server, Azure SQL en Azure Synapse Analytics. Het exporteren van een database van Azure SQL Database naar een on-premises SQL Server-exemplaar, of van SQL Server naar Azure SQL Database, zijn voorbeelden van databaseoverdraagbaarheid. SqlPackage biedt ondersteuning voor databaseportabiliteit via de acties Exporteren en Importeren , waarmee BACPAC-bestanden worden gemaakt en gebruikt. SqlPackage biedt ook ondersteuning voor databaseportabiliteit via de acties Extraheren en Publiceren , die DACPAC-bestanden maken en gebruiken. Deze kunnen de gegevens rechtstreeks bevatten of verwijzen naar gegevens die zijn opgeslagen in Azure Blob Storage.

  • Exporteren: hiermee exporteert u een verbonden SQL-database, inclusief databaseschema en gebruikersgegevens, naar een BACPAC-bestand (.bacpac).

  • Importeren: importeert het schema en de tabelgegevens uit een BACPAC-bestand in een nieuwe gebruikersdatabase.

Uitrol

Database-implementaties zijn het proces voor het bijwerken van een databaseschema dat overeenkomt met de gewenste status, zoals het toevoegen van kolommen aan een tabel of het wijzigen van de inhoud van een opgeslagen procedure. SqlPackage ondersteunt database-implementaties via de acties Publiceren en extraheren . De actie Publiceren werkt een databaseschema bij zodat het overeenkomt met de inhoud van een DACPAC-bronbestand, terwijl met de actie Ophalen een toepassingsbestand (.dacpac) met het schema of schema en gebruikersgegevens van een verbonden SQL-database wordt gemaakt. SqlPackage maakt implementaties mogelijk voor zowel nieuwe als bestaande databases van hetzelfde artefact (.dacpac) door automatisch een implementatieplan te maken dat de benodigde wijzigingen toepast op de doeldatabase. Het implementatieplan kan worden beoordeeld voordat u de wijzigingen toepast op de doeldatabase met de acties Script of DeployReport.

  • Extraheer: hiermee maakt u een toepassingsbestand (.dacpac) met het schema of schema en de gebruikersgegevens uit een verbonden SQL-database.

  • Publiceren: werkt een databaseschema incrementeel bij zodat het overeenkomt met het schema van een DACPAC-bronbestand. Als de database niet op de server bestaat, wordt deze door de publicatiebewerking gemaakt. Anders wordt een bestaande database bijgewerkt.

  • DeployReport: hiermee maakt u een XML-rapport met de wijzigingen die een publicatieactie zou ondernemen.

  • DriftReport: hiermee maakt u een XML-rapport dat de wijzigingen vertegenwoordigt die zijn toegepast op een geregistreerde database sinds deze voor het laatst is geregistreerd.

  • Script: hiermee maakt u een Transact-SQL incrementeel updatescript waarmee het schema van een doel wordt bijgewerkt zodat deze overeenkomt met het schema van een bron.

Opdrachtregel-syntaxis

SqlPackage initieert de acties die zijn opgegeven met behulp van de parameters, eigenschappen en SQLCMD-variabelen die zijn opgegeven op de opdrachtregel.

SqlPackage {parameters} {properties} {SQLCMD variables}

Meer informatie over de opdrachtregelsyntaxis van SqlPackage vindt u in de sqlPackage CLI-verwijzing en afzonderlijke actiepagina's.

Hulpprogrammaopdrachten

Versie

Geeft de sqlpackage-versie weer als een buildnummer. Kan worden gebruikt in interactieve prompts en in geautomatiseerde pijplijnen.

SqlPackage /Version

Hulp

U kunt sqlPackage-gebruiksgegevens weergeven met behulp van /? of /help:True.

SqlPackage /?

Voor informatie over parameters en eigenschappen die specifiek zijn voor een bepaalde actie, gebruikt u de Help-parameter naast de parameter van die actie.

SqlPackage /Action:Publish /?

Authenticatie

SqlPackage verifieert met behulp van methoden die beschikbaar zijn in SqlClient. Het configureren van het verificatietype kan worden uitgevoerd via de verbindingsreeksparameters voor elke SqlPackage-actie (/SourceConnectionString en /TargetConnectionString) of via afzonderlijke parameters voor verbindingseigenschappen. De volgende verificatiemethoden worden ondersteund in een verbindingsreeks:

  • SQL Server-verificatie
  • Active Directory-verificatie (Windows)
  • Microsoft Entra-authenticatie
    • Gebruikersnaam/wachtwoord
    • Geïntegreerde verificatie
    • Universele verificatie
    • beheerde identiteit
    • Service principal

Beheerde identiteit

Opmerking

Microsoft Entra ID voorheen Azure Active Directory (Azure AD) werd genoemd.

In geautomatiseerde omgevingen is de door Microsoft Entra beheerde identiteit de aanbevolen verificatiemethode. Deze methode vereist geen referenties door te geven aan SqlPackage tijdens runtime, omdat SqlPackage beheerde identiteiten gebruikt om verbinding te maken met databases die ondersteuning bieden voor Microsoft Entra-verificatie en om Microsoft Entra-tokens te verkrijgen, zonder referentiesbeheer. Wanneer de beheerde identiteit is geconfigureerd voor de omgeving waarin de SqlPackage-actie wordt uitgevoerd, kan de sqlPackage-actie die identiteit gebruiken om te verifiëren bij Azure SQL. Zie de documentatie over beheerde identiteiten voor meer informatie over het configureren van een beheerde identiteit voor uw omgeving.

Een voorbeeld van een verbindingsreeks met een door het systeem toegewezen beheerde identiteit is:

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

Beheerde identiteiten worden ondersteund in zowel Azure DevOps als GitHub Actions CI/CD-pijplijnen.

Service-principal

Opmerking

Microsoft Entra ID voorheen Azure Active Directory (Azure AD) werd genoemd.

Service-principals voor Microsoft Entra-toepassingen zijn beveiligingsobjecten in een Microsoft Entra-toepassing die definiëren wat een toepassing in een bepaalde tenant kan doen. Ze worden ingesteld in Azure Portal tijdens het registratieproces van de toepassing en geconfigureerd voor toegang tot Azure-resources, zoals Azure SQL. Zie de documentatie van de service-principal voor meer informatie over het configureren van een service-principal voor uw omgeving.

Wanneer u SqlPackage met een service-principal gebruikt, kunt u een toegangstoken ophalen en doorgeven aan SqlPackage. Het toegangstoken kan worden opgehaald met behulp van de Azure PowerShell-module of de Azure CLI. In dit proces houdt het aanroepende systeem controle over het vernieuwen of ongeldig maken van tokens. Het toegangstoken kan worden doorgegeven aan SqlPackage met behulp van de /at parameter.

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

U kunt ook de client-ID en het secret van de service-principal doorgeven aan SqlPackage in de verbindingsreeks. De indeling van de verbindingsreeks bevat Authentication=Active Directory Service Principal; en User Id=AppId; Password=<password>. Wanneer de referenties van de service-principal worden doorgegeven in de verbindingsreeks, is de /at parameter niet vereist en vernieuwt SqlPackage de verificatie indien nodig tijdens de bewerking.

Service principals worden ondersteund in zowel Azure DevOps als in GitHub Actions CI/CD-pijplijnen.

Omgevingsvariabelen

Groepsgewijze verbindingen

Groepsgewijze verbindingen kunnen worden ingeschakeld voor alle verbindingen die door SqlPackage zijn gemaakt door de CONNECTION_POOLING_ENABLED omgevingsvariabele in te stellen op True. Deze instelling wordt aanbevolen voor bewerkingen met Microsoft Entra-gebruikersnaam- en wachtwoordverbindingen om beperking door de Microsoft Authentication Library (MSAL) te voorkomen.

Tijdelijke bestanden

Tijdens SqlPackage-bewerkingen worden de tabelgegevens naar tijdelijke bestanden geschreven vóór compressie of na decompressie. Voor grote databases kunnen deze tijdelijke bestanden een aanzienlijke hoeveelheid schijfruimte in beslag nemen, maar hun locatie kan worden opgegeven. De export- en extractbewerkingen bevatten een optionele eigenschap die moet worden opgegeven /p:TempDirectoryForTableData om de standaardwaarde van SqlPackage te overschrijven.

De .NET API GetTempPath wordt gebruikt om de standaardwaarde in SqlPackage te bepalen.

Voor Windows worden de volgende omgevingsvariabelen gecontroleerd in de volgende volgorde en wordt het eerste pad gebruikt:

  1. Het pad dat is opgegeven door de TMP omgevingsvariabele.
  2. Het pad dat is opgegeven door de TEMP omgevingsvariabele.
  3. Het pad dat is opgegeven door de USERPROFILE omgevingsvariabele.
  4. De Windows-map.

Als voor Linux en macOS het pad niet is opgegeven in de TMPDIR omgevingsvariabele, wordt het standaardpad /tmp/ gebruikt.

SqlPackage- en databasegebruikers

Ingesloten databasegebruikers zijn opgenomen in SqlPackage-bewerkingen. Het wachtwoordgedeelte van de definitie wordt echter ingesteld op een willekeurig gegenereerde tekenreeks door SqlPackage, de bestaande waarde wordt niet overgedragen. Het is raadzaam om het wachtwoord van de nieuwe gebruiker opnieuw in te stellen op een veilige waarde na het importeren van een .bacpac of de implementatie van een .dacpac. In een geautomatiseerde omgeving kunnen de wachtwoordwaarden worden opgehaald uit een beveiligd sleutelarchief, zoals Azure Key Vault, in een stap na SqlPackage.

Uitbreidbaarheid

SqlPackage biedt ondersteuning voor uitbreidbaarheid via het Managed Extensibility Framework (MEF) en maakt geavanceerde scenario's mogelijk via aangepaste onderdelen die inzenders worden genoemd. Met deze extensies kunt u aanpassen hoe SqlPackage bestanden publiceert .dacpac , zodat teams standaarden kunnen afdwingen of projectspecifieke logica kunnen automatiseren. Implementatiebijdragers worden uitgevoerd als onderdeel van het publicatieproces, nadat het implementatieplan is gegenereerd, maar voordat het wordt uitgevoerd. Deze inzenders kunnen het implementatieplan openen en wijzigen met behulp van een DeploymentPlanModifier klasseobject om stappen toe te voegen, te verwijderen of opnieuw te ordenen. Zie Gebruik implementatiebijdragers om de database opbouw en implementatie aan te passen om aan de slag te gaan met de uitbreidbaarheid van de implementatie.

SqlPackage detecteert en laadt inzenderassembly's door te scannen op bibliotheken met dynamische koppelingen (.dll bestanden) in dezelfde map als het uitvoerbare sqlPackage-bestand en de locaties die zijn opgegeven via optionele opdrachtregeleigenschap /p:AdditionalDeploymentContributorPaths. Hoewel dit flexibele aanpassing mogelijk maakt, introduceert het ook belangrijke beveiligingsoverwegingen.

Belangrijk

Omdat SqlPackage MEF gebruikt om tijdens runtime dynamisch dynamische koppelingsbibliotheken (.dll bestanden) te laden, kunnen assembly's die naast het uitvoerbare bestand sqlPackage worden geplaatst, worden uitgevoerd als onderdeel van het implementatieproces. Een kwaadwillende actor kan dit gedrag misbruiken door gemanipuleerde of niet-geautoriseerde extensies te introduceren die willekeurige code uitvoeren.

Het is uw verantwoordelijkheid om ervoor te zorgen dat alle gecompileerde extensiebestanden die worden gebruikt met SqlPackage veilig zijn en afkomstig zijn van vertrouwde bronnen. U wordt aangeraden de toegang tot de map SqlPackage te beheren en de integriteit van alle aangepaste of externe onderdelen te valideren.

Verzameling van gebruiksgegevens

SqlPackage bevat internetfuncties waarmee anonieme functiegebruik en diagnostische gegevens naar Microsoft kunnen worden verzameld en verzonden.

SqlPackage kan standaardinformatie over computergebruik en prestaties verzamelen, die naar Microsoft kan worden verzonden en geanalyseerd om de kwaliteit, beveiliging en betrouwbaarheid van SqlPackage te verbeteren.

SqlPackage verzamelt geen gebruikersspecifieke of persoonlijke gegevens. SqlPackage genereert een willekeurige GUID voor elke computer waarop deze wordt uitgevoerd en gebruikt deze waarde voor alle gebeurtenissen die door sqlPackage worden verzonden om een benadering te bieden van één gebruiker voor diagnostische doeleinden.

Zie de privacyverklaring van Microsoft en de aanvulling op de privacyverklaring van SQL Server voor meer informatie.

Telemetrierapportage uitschakelen

Als u telemetrieverzameling en -rapportage wilt uitschakelen, werkt u de omgevingsvariabele DACFX_TELEMETRY_OPTOUT bij naar true of 1.

Ondersteuning

De DacFx-bibliotheek en het hulpprogramma SqlPackage CLI volgen het moderne levenscyclusbeleid van Microsoft. Alle beveiligingsupdates, fixes en nieuwe functies worden alleen uitgebracht in de nieuwste puntversie van de primaire versie. Het onderhouden van uw DacFx- of SqlPackage-installaties op de huidige versie helpt ervoor te zorgen dat u alle toepasselijke bugfixes tijdig ontvangt.

Hulp krijgen bij SqlPackage, functieaanvragen indienen en problemen melden in de DacFx GitHub-opslagplaats.

Ondersteunde SQL-aanbiedingen

SqlPackage en DacFx ondersteunen alle ondersteunde SQL-versies op het moment van de release SqlPackage/DacFx. Een SqlPackage-release op 14 januari 2022 ondersteunt bijvoorbeeld alle ondersteunde versies van SQL in januari 2022. Zie het SQL-ondersteuningsbeleid voor meer informatie over SQL-ondersteuningsbeleid.

Naast SQL Server biedt SqlPackage en DacFx ondersteuning voor Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics en Synapse Data Warehouse in Microsoft Fabric.

Volgende stappen