SqlPackage

  • Artikel
  • 5 Minuten Lesedauer

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. In Version 18.6 hinzugefügt.

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

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 = 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 Pipelinesverwendet 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)
  • Authentifizierung über Azure Active Directory
    • Benutzername/Kennwort
    • Integrierte Authentifizierung
    • Universelle Authentifizierung
    • Verwaltete Identität
    • Dienstprinzipal

Verwaltete Identität

In automatisierten Umgebungen ist die verwaltete Azure Active Directory-Identität die empfohlene Authentifizierungsmethode. Diese Methode erfordert keine Übergabe von Anmeldeinformationen an SqlPackage zur Laufzeit. Die verwaltete Identität wird für die Umgebung konfiguriert, in der die SqlPackage-Aktion ausgeführt wird, und die SqlPackage-Aktion verwendet diese Identität, um sich bei Azure SQL zu authentifizieren. Weitere Informationen zum Konfigurieren der 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 Azure Active Directory-Benutzernamen/Kennwort-Verbindungen empfohlen, um eine MSAL-Drosselung 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 Standardwert wird von GetTempPath innerhalb von SqlPackage festgelegt.

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.

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.

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