Freigeben über

SqlPackage

  • Artikel

SqlPackage ist ein Befehlszeilenhilfsprogramm, das die Datenbankentwicklungsaufgaben automatisiert, indem es einige der öffentlichen DacFx-APIs (Data-Tier Application Framework) verfügbar macht. Die primären Anwendungsfälle für SqlPackage konzentrieren sich auf die Portabilität und Bereitstellungen der Datenbank für die SQL Server-, Azure SQL- und Azure Synapse Analytics-Datenbankfamilien. SqlPackage kann mithilfe von Azure Pipelines und GitHub Actions oder anderen CI/CD-Tools automatisiert werden.

Aktuelle Version herunterladen Weitere Informationen über die neueste Version finden Sie in den Versionshinweisen.

Hinweis

Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.

Portabilität

Die Portabilität der Datenbank ist die Möglichkeit, ein Datenbankschema und Daten zwischen verschiedenen Instanzen von SQL Server, Azure SQL und Azure Synapse Analytics zu verschieben. Das Exportieren einer Datenbank aus Azure SQL-Datenbank in eine lokale SQL Server-Instanz oder von SQL Server in Azure SQL-Datenbank sind Beispiele für die Portabilität der Datenbank. SqlPackage unterstützt die Portabilität der Datenbank über die Aktionen Exportieren und Importieren, die BACPAC-Dateien erstellen und nutzen. SqlPackage unterstützt auch die Datenbankübertragbarkeit über die Aktionen Extrahieren und Veröffentlichen, die DACPAC-Dateien erstellen und nutzen, die entweder die Daten direkt enthalten oder auf Daten verweisen, die in Azure Blob Storage gespeichert sind.

  • Export: Exportiert eine verbundene SQL-Datenbank, einschließlich des Datenbankschemas und der Benutzerdaten, in eine BACPAC-Datei (.bacpac)

  • Import: Importiert das Schema und die Tabellendaten aus einer BACPAC-Datei in eine neue Benutzerdatenbank

Bereitstellungen

Datenbankbereitstellungen sind der Prozess der Aktualisierung eines Datenbankschemas, um einem gewünschten Zustand zu entsprechen, z. B. das Hinzufügen von Spalten zu einer Tabelle oder das Ändern des Inhalts einer gespeicherten Prozedur. SqlPackage unterstützt Datenbankbereitstellungen über die Aktionen Veröffentlichen und Extrahieren . Die Aktion „Veröffentlichen“ aktualisiert ein Datenbankschema so, dass es mit dem Inhalt einer DACPAC-Quelldatei übereinstimmt, während die Aktion „Extrahieren“ eine Datenschichtanwendungsdatei (DACPAC) erstellt, die das Schema oder das Schema und Benutzerdaten aus einer verbundenen SQL-Datenbank enthält. SqlPackage ermöglicht Bereitstellungen für neue oder vorhandene Datenbanken aus demselben Artefakt (.dacpac), indem automatisch ein Bereitstellungsplan erstellt wird, der die erforderlichen Änderungen auf die Zieldatenbank anwendet. Der Bereitstellungsplan kann überprüft werden, bevor die Änderungen mit den Aktionen Skript oder DeployReport auf die Zieldatenbank angewendet werden.

  • Extract: Erstellt eine Datenschichtanwendungsdatei (.dacpac), die das Schema oder das Schema und die Benutzerdaten aus einer verbundenen SQL-Datenbank enthält

  • Veröffentlichen: Aktualisiert ein Datenbankschema inkrementell, sodass dieses dem Schema einer DACPAC-Quelldatei entspricht Wenn die Datenbank auf dem Server nicht vorhanden ist, wird sie durch den Veröffentlichungsvorgang erstellt. Andernfalls wird eine vorhandene Datenbank aktualisiert.

  • DeployReport: Erstellt einen XML-Bericht der Änderungen, die durch eine Veröffentlichungsaktion vorgenommen würden.

  • DriftReport: Erstellt einen XML-Bericht der Änderungen, die seit der letzten Registrierung an einer registrierten Datenbank vorgenommen wurden.

  • Script: Erstellt ein inkrementelles Transact-SQL-Updateskript, durch das das Schema eines Ziels aktualisiert wird, sodass es dem Schema einer Quelle entspricht.

Befehlszeilensyntax

SqlPackage initiiert die angegebenen Aktionen mithilfe der Parameter, Eigenschaften und SQLCMD-Variablen, die in der Befehlszeile angegeben sind.

SqlPackage {parameters} {properties} {SQLCMD variables}

Weitere Informationen zur SqlPackage-Befehlszeilensyntax finden Sie in der SqlPackage CLI-Referenz und auf einzelnen Aktionsseiten.

Hilfsprogrammbefehle

Version

Zeigt die Version von SqlPackage als Buildnummer. Kann in interaktiven Eingabeaufforderungen und automatisierten Pipelines verwendet werden.

SqlPackage /Version

Hilfe

Sie können SqlPackage-Nutzungsinformationen mithilfe von /? oder /help:True anzeigen.

SqlPackage /?

Verwenden Sie für Parameter- und Eigenschafteninformationen, die für eine bestimmte Aktion spezifisch sind, zusätzlich zum Parameter dieser Aktion den Help-Parameter.

SqlPackage /Action:Publish /?

Authentifizierung

SqlPackage wird mit den in SqlClient verfügbaren Methoden authentifiziert. Die Konfiguration des Authentifizierungstyps kann über die Verbindungszeichenfolgenparameter für jede SqlPackage-Aktion (/SourceConnectionString und /TargetConnectionString) oder über einzelne Parameter für Verbindungseigenschaften erfolgen. Die folgenden Authentifizierungsmethoden werden in einer Verbindungszeichenfolge unterstützt:

  • SQL Server-Authentifizierung
  • Active Directory-Authentifizierung (Windows)
  • Microsoft Entra-Authentifizierung
    • Benutzername/Kennwort
    • Integrierte Authentifizierung
    • Universelle Authentifizierung
    • Verwaltete Identität
    • Dienstprinzipal

Verwaltete Identität

Hinweis

Microsoft Entra ID war zuvor als Azure Active Directory (Azure AD) bekannt.

In automatisierten Umgebungen ist die verwaltete Microsoft Entra-Identität die empfohlene Authentifizierungsmethode. Diese Methode erfordert zur Laufzeit keine Übergabe von Anmeldeinformationen an SqlPackage, da SqlPackage verwaltete Identitäten verwendet, um eine Verbindung mit Datenbanken herzustellen, die die Microsoft Entra-Authentifizierung unterstützen, und Microsoft Entra-Token ohne Anmeldeinformationsverwaltung abzurufen. Wenn die verwaltete Identität für die Umgebung konfiguriert wird, in der die SqlPackage-Aktion ausgeführt wird, kann die SqlPackage-Aktion diese Identität verwenden, um sich bei Azure SQL zu authentifizieren. Weitere Informationen zum Konfigurieren einer verwalteten Identität für Ihre Umgebung finden Sie in der Dokumentation zur verwalteten Identität.

Ein Beispiel für eine Verbindungszeichenfolge mit systemseitig zugewiesener verwalteter Identität ist:

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

Verwaltete Identitäten werden in CI/CD-Pipelines von Azure DevOps- und GitHub-Aktionen unterstützt.

Dienstprinzipal

Hinweis

Microsoft Entra ID war zuvor als Azure Active Directory (Azure AD) bekannt.

Microsfot Entra-Anwendungsdienstprinzipale sind Sicherheitsobjekte innerhalb einer Microsoft Entra-Anwendung, die definieren, was eine Anwendung in einem bestimmten Mandanten tun kann. Sie werden während des Anwendungsregistrierungsprozesses im Azure-Portal eingerichtet und für den Zugriff auf Azure-Ressourcen wie Azure SQL konfiguriert. Weitere Informationen zum Konfigurieren eines Dienstprinzipals für Ihre Umgebung finden Sie in der Dienstprinzipaldokumentation.

Wenn Sie SqlPackage mit einem Dienstprinzipal verwenden, kann es erforderlich sein, das Zugriffstoken abzurufen und an SqlPackage zu übergeben. Das Zugriffstoken kann mithilfe des Azure PowerShell-Moduls oder der Azure CLI abgerufen werden. Das Zugriffstoken kann mithilfe des /at -Parameters an SqlPackage übergeben werden.

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

Verwaltete Identitäten werden in CI/CD-Pipelines von Azure DevOps- und GitHub-Aktionen unterstützt.

Umgebungsvariablen

Verbindungspooling

Das Verbindungspooling kann für alle von SqlPackage hergestellten Verbindungen aktiviert werden, indem die Umgebungsvariable auf CONNECTION_POOLING_ENABLED festgelegt wird True. Diese Einstellung wird für Vorgänge mit Microsoft Entra-Benutzernamen- und Kennwortverbindungen empfohlen, um eine Drosselung durch die Microsoft Authentication Library (MSAL) zu vermeiden.

Temporäre Dateien

Während SqlPackage-Operationen werden die Tabellendaten vor der Komprimierung oder nach der Dekomprimierung in temporäre Dateien geschrieben. Bei großen Datenbanken können diese temporären Dateien viel Speicherplatz beanspruchen, aber ihr Speicherort kann angegeben werden. Die Export- und Extrahierungsvorgänge enthalten eine optionale Eigenschaft, die angegeben /p:TempDirectoryForTableData werden muss, um den Standardwert von SqlPackage zu überschreiben.

Der GetTempPath der .NET-API wird verwendet, um den Standardwert in SqlPackage zu bestimmen.

Für Windows werden die folgenden Umgebungsvariablen in der folgenden Reihenfolge überprüft und der erste vorhandene Pfad verwendet:

  1. Den durch die TMP-Umgebungsvariable angegebenen Pfad.
  2. Den durch die TEMP-Umgebungsvariable angegebenen Pfad.
  3. Den durch die USERPROFILE-Umgebungsvariable angegebenen Pfad.
  4. Das Windows-Verzeichnis.

Wenn der Pfad für Linux und macOS nicht in der Umgebungsvariable TMPDIR angegeben ist, wird der Standardpfad /tmp/ verwendet.

SqlPackage- und Datenbankbenutzer

Enthaltene Datenbankbenutzer werden in SqlPackage-Vorgänge einbezogen. Der Kennwortteil der Definition wird von SqlPackage jedoch auf eine zufällig generierte Zeichenfolge festgelegt, der vorhandene Wert wird nicht übertragen. Es wird empfohlen, das Kennwort des neuen Benutzers nach dem Import einer .bacpac- oder der Bereitstellung einer .dacpac-Datei auf einen sicheren Wert zurückzusetzen. In einer automatisierten Umgebung können die Kennwortwerte in einem Schritt nach SqlPackage aus einem sicheren Keystore wie Azure Key Vault abgerufen werden.

Sammlung von Verwendungsdaten

SqlPackage enthält internetfähige Features, die anonyme Daten zur Featurenutzung und Diagnose sammeln und an Microsoft senden können.

SqlPackage sammelt möglicherweise Standardinformationen zu Computer, Nutzung und Leistung, die an Microsoft übertragen und dort analysiert werden können, um die Qualität, Sicherheit und Zuverlässigkeit von SqlPackage zu verbessern.

SqlPackage sammelt keine benutzerspezifischen oder personenbezogenen Informationen. Um sich einzelnen Benutzer*innen zu Diagnosezwecken anzunähern, generiert SqlPackage eine zufällige GUID für jeden Computer, auf dem es ausgeführt wird, und verwendet diesen Wert für alle gesendeten Ereignisse.

Ausführliche Informationen finden Sie in den Datenschutzbestimmungen von Microsoft und den Ergänzenden Datenschutzbestimmungen zu SQL Server.

Deaktivieren der Telemetrieberichterstellung

Aktualisieren Sie die Umgebungsvariable DACFX_TELEMETRY_OPTOUT auf true oder 1, um die Telemetriesammlung und -berichterstellung zu deaktivieren.

Support

Die DacFx-Bibliothek und das SQLPackage-CLI-Tool haben die Microsoft Modern Lifecycle-Richtlinie übernommen. Alle Sicherheitsupdates, Fixes und neue Features werden nur in der neuesten Punktversion der Hauptversion veröffentlicht. Wenn Sie Ihre DacFx- oder SqlPackage-Installationen auf die aktuelle Version aktualisieren, können Sie sicherstellen, dass Sie alle anwendbaren Fehlerbehebungen rechtzeitig erhalten.

Im DacFx GitHub-Repository erhalten Sie Hilfe zu SqlPackage, können Featureanfragen übermitteln und Probleme melden.

Unterstützte SQL-Angebote

SqlPackage und DacFx unterstützen alle unterstützten SQL-Versionen zum Zeitpunkt der Veröffentlichung der SqlPackage/DacFx-Version. Ein SqlPackage-Release vom 14. Januar 2022 unterstützt beispielsweise alle unterstützten Versionen von SQL vom 14. Januar 2022. Weitere Informationen zu SQL-Supportrichtlinien finden Sie unter SQL-Supportrichtlinie.

Zusätzlich zu SQL Server unterstützen SqlPackage und DacFx Azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics und Synapse Data Warehouse in Microsoft Fabric.

Nächste Schritte