SqlPackage

  • Artikel

SqlPackage ist ein Befehlszeilenhilfsprogramm, das die folgenden Aufgaben bei der Datenbankentwicklung automatisiert, indem einige der öffentlichen APIs des DAC-Frameworks (Data-Tier Application Framework, DACFx) verfügbar gemacht werden:

  • Version: Gibt die Buildnummer der SqlPackage-Anwendung zurück.

  • 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.

  • 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

  • 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.

Mit dem Befehlszeilentool SqlPackage können diese Aktionen zusammen mit aktionsspezifischen Parametern und Eigenschaften angegeben 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.

Befehlszeilensyntax

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

SqlPackage {parameters} {properties} {SQLCMD variables}

Exitcodes

SqlPackage-Befehle geben die folgenden Exitcodes zurück:

  • 0 = Erfolg
  • Ungleich 0 = Fehler

Verwendungsbeispiel

Weitere Beispiele sind auf den Seiten der einzelnen Aktionen verfügbar.

Erstellen einer DACPAC-Datei des aktuellen Datenbankschemas:

SqlPackage /TargetFile:"C:\sqlpackageoutput\output_current_version.dacpac" /Action:Extract /SourceServerName:"." /SourceDatabaseName:"Contoso.Database"

Parameter

Einige Parameter werden von den SqlPackage-Aktionen gemeinsam verwendet. Die folgende Tabelle bietet eine Übersicht über die Parameter. Um weitere Informationen zu erhalten, klicken Sie auf die entsprechende Überschrift für die Aktion.

Parameter Kurzform Extrahieren Veröffentlichen Export Importieren DeployReport DriftReport Skript
/AccessToken: /at x x x x x x x
/ClientId: /cid w
/DeployScriptPath: /dsp x x
/DeployReportPath: /drp x x
/Diagnostics: /d x x x x x x x
/DiagnosticsFile: /df x x x x x x x
/MaxParallelism: /mp x x x x x x x
/OutputPath: /op x x x
/OverwriteFiles: /of x x x x x x
/Profile: /pr x x x
/Properties: /p x x x x x x
/Quiet: /q x x x x x x x
/Secret: /secr w
/SourceConnectionString: /scs x x x x x
/SourceDatabaseName: /sdn x x x x x
/SourceEncryptConnection: /sec x x x x x
/SourceFile: /sf x x x x
/SourcePassword: /sp x x x x x
/SourceServerName: /ssn x x x x x
/SourceTimeout: /st x x x x x
/SourceTrustServerCertificate: /stsc x x x x x
/SourceUser: /su x x x x x
/TargetConnectionString: /tcs x x x x
/TargetDatabaseName: /tdn x x x x x
/TargetEncryptConnection: /tec x x x x x
/TargetFile: /tf x x x x
/TargetPassword: /tp x x x x x
/TargetServerName: /tsn x x x x x
/TargetTimeout: /tt x x x x x
/TargetTrustServerCertificate: /ttsc x x x x x
/TargetUser: /tu x x x x x
/TenantId: /tid x x x x x x x
/UniversalAuthentication: /ua x x x x x x x
/Variables: /v x x

Eigenschaften

SqlPackage-Aktionen unterstützen eine große Anzahl von Eigenschaften zum Ändern des Standardverhaltens einer Aktion. Weitere Informationen finden Sie auf den Seiten der jeweiligen Aktion.

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 keine Übergabe von Anmeldeinformationen an SqlPackage zur Laufzeit. 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;

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.

Nächste Schritte