Freigeben über

SqlPackage

  • Artikel

SqlPackage ist ein Befehlszeilenprogramm, das die Datenbankentwicklungsaufgaben automatisiert, indem einige der öffentlichen Data-Tier Application Framework (DacFx)-APIs verfügbar sind. Die primären Anwendungsfälle für SqlPackage konzentrieren sich auf datenbankübertragbarkeit und -bereitstellungen für die Datenbanken SQL Server, Azure SQL und Azure Synapse Analytics. SqlPackage kann mithilfe von Azure Pipelines und GitHub-Aktionen oder anderen CI/CD-Tools automatisiert werden.

Laden Sie die neueste Version herunter. 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.

Tragbarkeit

Die Datenbankübertragbarkeit 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 der Azure SQL-Datenbank in eine lokale SQL Server-Instanz oder von SQL Server in azure SQL-Datenbank sind Beispiele für die Datenbankübertragbarkeit. SqlPackage unterstützt die Datenbankübertragbarkeit über die Export - und Importaktionen , 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 referenzieren können, 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 Veröffentlichungsaktion aktualisiert ein Datenbankschema so, dass es mit dem Inhalt einer dacpac-Quelldatei übereinstimmt, während die Extrahieren-Aktion eine Datenebenenanwendungsdatei (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 Skript - oder DeployReport-Aktionen 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 nicht auf dem Server vorhanden ist, erstellt der Veröffentlichungsvorgang sie. Andernfalls wird eine vorhandene Datenbank aktualisiert.

  • DeployReport-: Erstellt einen XML-Bericht, der die Änderungen darstellt, die eine Veröffentlichungsaktion ausführen würde.

  • DriftReport-: Erstellt einen XML-Bericht, der die Änderungen darstellt, die seit der letzten Registrierung auf eine registrierte Datenbank angewendet 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 in der Befehlszeile angegebenen Aktionen mithilfe der Parameter, Eigenschaften und SQLCMD-Variablen.

SqlPackage {parameters} {properties} {SQLCMD variables}

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

Hilfsbefehle

Version

Zeigt die sqlpackage-Version als Buildnummer an. Kann in interaktiven Eingabeaufforderungen und in automatisierten Pipelinesverwendet werden.

SqlPackage /Version

Hilfe

Sie können SqlPackage-Verwendungsinformationen mithilfe von /? oder /help:Trueanzeigen.

SqlPackage /?

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

SqlPackage /Action:Publish /?

Authentifizierung

SqlPackage authentifiziert sich mithilfe von Methoden, die in SqlClient verfügbar sind. Die Konfiguration des Authentifizierungstyps kann über die Verbindungszeichenfolgenparameter für jede SqlPackage-Aktion (/SourceConnectionString und /TargetConnectionString) oder über einzelne Parameter für Verbindungseigenschaften erreicht werden. 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
    • Service Principal

Verwaltete Identität

Hinweis

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

In automatisierten Umgebungen ist die von Microsoft Entra verwaltete 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 Anmeldeinformationenverwaltung abzurufen. Wenn die verwaltete Identität für die Umgebung konfiguriert ist, 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.

Eine Beispielverbindungszeichenfolge mit vom System zugewiesener verwalteter Identität lautet:

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

Verwaltete Identitäten werden sowohl in Azure DevOps als auch in GitHub-Aktionen CI/CD-Pipelines unterstützt.

Service Principal

Hinweis

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

Microsoft Entra-Anwendungsprinzipale sind Sicherheitsobjekte in 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, können Sie ein Zugriffstoken abrufen und an SqlPackage übergeben. Das Zugriffstoken kann mithilfe des Azure PowerShell-Moduls oder der Azure CLI abgerufen werden. In diesem Prozess behält das aufrufende System die Kontrolle über die Aktualisierung oder die Ungültigmachung von Tokens. 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;"

Alternativ können Sie die Dienstprinzipalclient-ID und den geheimen Schlüssel in der Verbindungszeichenfolge an SqlPackage übergeben. Das Verbindungszeichenfolgenformat enthält Authentication=Active Directory Service Principal; und User Id=AppId; Password=<password>. Wenn die Dienstprinzipalanmeldeinformationen in der Verbindungszeichenfolge übergeben werden, ist der /at-Parameter nicht erforderlich, und SqlPackage aktualisiert die Authentifizierung bei Bedarf während des Vorgangs.

Dienstprinzipale werden in CI/CD-Pipelines von Azure DevOps und GitHub Actions unterstützt.

Umgebungsvariablen

Verbindungspooling

Verbindungspooling kann für alle Verbindungen von SqlPackage aktiviert werden, indem die CONNECTION_POOLING_ENABLED Umgebungsvariable auf True festgelegt wird. 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-Vorgängen 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 einen erheblichen Speicherplatz belegen, aber ihr Speicherort kann angegeben werden. Die Export- und Extrahierungsvorgänge enthalten eine optionale Eigenschaft zur Angabe von /p:TempDirectoryForTableData, um den Standardwert von SqlPackage außer Kraft zu setzen.

Die .NET-API GetTempPath 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 pfad, der vorhanden ist, wird verwendet:

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

Bei Linux und macOS wird der Standardpfad /tmp/ verwendet, wenn der Pfad nicht in der TMPDIR Umgebungsvariable angegeben ist.

SqlPackage- und Datenbankbenutzer

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

Erweiterbarkeit

SqlPackage unterstützt die Erweiterbarkeit über das Managed Extensibility Framework (MEF), wodurch erweiterte Szenarien über benutzerdefinierte Komponenten ermöglicht werden, die als Mitwirkende bezeichnet werden. Diese Erweiterungen können anpassen, wie SqlPackage Dateien veröffentlicht .dacpac , sodass Teams Standards erzwingen oder projektspezifische Logik automatisieren können. Mitwirkende an der Bereitstellung werden als Teil des Veröffentlichungsprozesses ausgeführt, nachdem der Bereitstellungsplan generiert wurde, aber bevor er ausgeführt wird. Diese Mitwirkenden können mithilfe eines DeploymentPlanModifier Klassenobjekts auf den Bereitstellungsplan zugreifen und diesen ändern, um Schritte hinzuzufügen, zu entfernen oder neu anzuordnen. Informationen zu den ersten Schritten mit der Bereitstellungserweiterung finden Sie unter Verwenden von Bereitstellungsmitwirkenden zum Anpassen des Datenbankbuilds und der Bereitstellung.

SqlPackage ermittelt und lädt Assemblys mit Mitwirkenden, indem nach Dynamic Link Libraries (.dll-Dateien) gesucht wird, die sich im selben Verzeichnis wie die ausführbare SqlPackage-Datei sowie in den Speicherorten befinden, die von der optionalen Befehlszeileneigenschaft /p:AdditionalDeploymentContributorPaths angegeben werden. Dies ermöglicht zwar flexible Anpassungen, führt aber auch wichtige Sicherheitsaspekte ein.

Von Bedeutung

Da SqlPackage das MEF-Framework verwendet, um Dynamic Link Libraries (.dll-Dateien) zur Laufzeit dynamisch zu laden, können alle Assemblys, die neben der ausführbaren Datei von SqlPackage platziert werden, im Rahmen des Bereitstellungsprozesses ausgeführt werden. Ein böswilliger Akteur könnte dieses Verhalten ausnutzen, indem manipulierte oder nicht autorisierte Erweiterungen eingeführt werden, die beliebigen Code ausführen.

Es liegt in Ihrer Verantwortung, sicherzustellen, dass alle kompilierten Erweiterungsdateien, die mit SqlPackage verwendet werden, sicher sind und von vertrauenswürdigen Quellen stammen. Es wird empfohlen, den Zugriff auf den SqlPackage-Ordner zu steuern und die Integrität aller benutzerdefinierten oder Drittanbieterkomponenten zu überprüfen.

Sammlung von Verwendungsdaten

SqlPackage enthält internetfähige Features, die anonyme Featureverwendung und Diagnosedaten sammeln und an Microsoft senden können.

SqlPackage kann Standardcomputer-, Verwendungs- und Leistungsinformationen sammeln, die an Microsoft übertragen und analysiert werden können, um die Qualität, Sicherheit und Zuverlässigkeit von SqlPackage zu verbessern.

SqlPackage sammelt keine benutzerspezifischen oder persönlichen Informationen. Um einen einzelnen Benutzer für Diagnosezwecke anzunähern, generiert SqlPackage eine zufällige GUID für jeden Computer, auf dem er 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

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

Unterstützung

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

Erhalten Sie Hilfe zu SqlPackage, senden Sie Featureanforderungen und melden Sie Probleme im DacFx GitHub-Repository.

Unterstützte SQL-Angebote

SqlPackage und DacFx unterstützen alle unterstützten SQL-Versionen zum Zeitpunkt der SqlPackage/DacFx-Version. Beispielsweise unterstützt eine SqlPackage-Version am 14. Januar 2022 alle unterstützten Versionen von SQL im Januar 14 2022. Weitere Informationen zu SQL-Supportrichtlinien finden Sie in der SQL-Supportrichtlinie.

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

Nächste Schritte