Teilen über

Behandeln von Leistungs- und anderen Problemen mit SqlPackage

  • Artikel

In einigen Szenarien dauern SqlPackage-Vorgänge länger als erwartet oder können nicht abgeschlossen werden. In diesem Artikel werden einige häufig vorgeschlagene Methoden zur Problembehandlung oder zur Verbesserung der Leistung dieser Vorgänge beschrieben. Beim Lesen der Dokumentationsseite für die jeweilige Aktion, um die empfohlenen verfügbaren Parameter und Eigenschaften zu verstehen, dient dieser Artikel als Ausgangspunkt für die Untersuchung von SqlPackage-Vorgängen.

Gesamtstrategie

Als Faustregel gilt, dass mit der .NET-Version von SqlPackage eine bessere Leistung erzielt werden kann als mit der über DacFramework.msi installierten .NET Framework-Version.

Wenn Sie das Dotnet-Tool von SqlPackage nicht installieren können, das das Ausführen von SqlPackage-Befehlen über die Eingabeaufforderung in einem beliebigen Verzeichnis ermöglicht, gehen Sie wie folgt vor:

  1. Laden Sie die ZIP-Datei für SqlPackage unter .NET 8 für Ihr Betriebssystem (Windows, macOS oder Linux) herunter.
  2. Entzippen Sie das Archiv anhand der Anleitung auf der Downloadseite.
  3. Öffnen Sie eine Eingabeaufforderung, und ändern Sie das Verzeichnis (cd) in den Ordner „SqlPackage“.

Es ist wichtig, dass Sie die neueste verfügbare Version von SqlPackage verwenden, da Leistungsverbesserungen und Fehlerbehebungen regelmäßig veröffentlicht werden.

Ersetzen des Import/Export-Diensts durch SqlPackage

Anstatt die Datenbank mit dem Import/Export-Dienst zu importieren oder zu exportieren, können Sie auch SqlPackage nutzen, um denselben Vorgang mit mehr Kontrolle über optionale Parameter und Eigenschaften durchzuführen.

Ein Beispielbefehl für „Import“ lautet:

./SqlPackage /Action:Import /sf:<source-bacpac-file-path> /tsn:<full-target-server-name> /tdn:<a new or empty database> /tu:<target-server-username> /tp:<target-server-password> /df:<log-file>

Ein Beispielbefehl für „Export“ lautet:

./SqlPackage /Action:Export /tf:<target-bacpac-file-path> /ssn:<full-source-server-name> /sdn:<source-database-name> /su:<source-server-username> /sp:<source-server-password> /df:<log-file>

Alternativ zu Benutzername und Kennwort kann die mehrstufige Authentifizierung zur Authentifizierung über die Microsoft Entra-Authentifizierung (vormals Azure Active Directory) mit mehrstufiger Authentifizierung verwendet werden. Ersetzen Sie /ua:true und /tid:"yourdomain.onmicrosoft.com" durch die Parameter „username“ (Benutzername) und „password“ (Kennwort).

Häufige Probleme

Timeoutfehler

Bei Problemen im Zusammenhang mit Timeouts kann die Verbindung zwischen SqlPackage und der SQL-Instanz mithilfe der folgenden Eigenschaften optimiert werden:

  • /p:CommandTimeout=: gibt das Befehlstimeout in Sekunden an, wenn eine Abfrage ausgeführt wird. Standard: 60
  • /p:DatabaseLockTimeout=: gibt das Timeout für Datenbanksperren in Sekunden an. -1 kann für eine unbefristete Wartezeit angegeben werden, Standardwert: 60
  • /p:LongRunningCommandTimeout=: gibt das Timeout für zeitintensive Befehle in Sekunden an. Der Standardwert 0 dient zum Angeben einer unbegrenzten Wartezeit.

Nutzung von Clientressourcen

Bei den Befehlen zum Exportieren und Extrahieren werden die Tabellendaten an ein temporäres Verzeichnis übergeben, um sie zu puffern, ehe sie in die BACPAC/DACPAC-Datei geschrieben werden. Dieser Speicherbedarf kann groß sein und bezieht sich auf die Gesamtgröße der zu exportierenden Daten. Geben Sie mit der Eigenschaft /p:TempDirectoryForTableData=<path> ein alternatives temporäres Verzeichnis an.

Das Schemamodell wird im Arbeitsspeicher kompiliert, sodass bei großen Datenbankschemata der Arbeitsspeicherbedarf auf dem Clientcomputer, auf dem SqlPackage ausgeführt wird, groß sein kann.

Geringe Nutzung von Serverressourcen

Standardmäßig legt SqlPackage die maximale Serverparallelität auf 8 fest. Wenn Sie eine geringe Nutzung von Serverressourcen beobachten, kann das Erhöhen des Werts des Parameters MaxParallelism die Leistung verbessern.

Zugriffstoken

Die Verwendung des Parameters /AccessToken: oder /at: ermöglicht die tokenbasierte Authentifizierung für SqlPackage, allerdings kann das Übergeben des Token an den Befehl schwierig sein. Wenn Sie ein Zugriffstokenobjekt in PowerShell parsen, übergeben Sie entweder explizit den Zeichenfolgenwert, oder schließen Sie den Verweis auf die Tokeneigenschaft in $() ein. Zum Beispiel:

$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken
# OR
SqlPackage /at:$($AccessToken_Object.Token)

Verbindung

Wenn SqlPackage keine Verbindung herstellen kann, ist die Verschlüsselung auf dem Server möglicherweise nicht aktiviert, oder das konfigurierte Zertifikat wird nicht von einer vertrauenswürdigen Zertifizierungsstelle ausgestellt (z. B. ein selbstsigniertes Zertifikat). Sie können den SqlPackage-Befehl ändern, um entweder eine Verbindung ohne Verschlüsselung herzustellen oder dem Serverzertifikat zu vertrauen. Die bewährte Methode besteht darin, sicherzustellen, dass eine vertrauenswürdige verschlüsselte Verbindung mit dem Server hergestellt werden kann.

  • Ohne Verschlüsselung verbinden: /SourceEncryptConnection:False oder /TargetEncryptConnection:False
  • Serverzertifikat vertrauen: /SourceTrustServerCertificate:True oder /TargetTrustServerCertificate:True

Beim Herstellen einer Verbindung mit einer SQL-Instanz wird möglicherweise eine der folgenden Warnmeldungen angezeigt, die darauf hinweisen, dass Befehlszeilenparameter möglicherweise Änderungen erfordern, um eine Verbindung mit dem Server herzustellen:

The settings for connection encryption or server certificate trust may lead to connection failure if the server is not properly configured.
The connection string provided contains encryption settings which may lead to connection failure if the server is not properly configured.

Weitere Informationen zu den Verbindungssicherheitsänderungen in SqlPackage finden Sie unter Verbesserungen der Verbindungssicherheit in SqlPackage 161.

Importaktionsfehler 2714 für Einschränkung

Beim Ausführen einer Importaktion erhalten Sie möglicherweise den Fehler 2714, wenn bereits ein Objekt vorhanden ist:

*** Error importing database:Could not import package.
Error SQL72014: Core Microsoft SqlClient Data Provider: Msg 2714, Level 16, State 5, Line 1 There is already an object named 'DF_Department_ModifiedDate_0FF0B724' in the database.
Error SQL72045: Script execution error. The executed script:
ALTER TABLE [HumanResources].[Department]
    ADD CONSTRAINT [DF_Department_ModifiedDate_] DEFAULT ('') FOR [ModifiedDate];

Dies sind die Ursachen und Lösungen zur Behebung dieses Fehlers:

  1. Stellen Sie sicher, dass das Ziel, in das Sie importieren, eine leere Datenbank ist.
  2. Wenn Ihre Datenbank Einschränkungen aufweist, die das DEFAULT-Attribut (bei dem SQL Server der Einschränkung einen zufälligen Namen zuweist) sowie eine explizit benannte Einschränkung verwenden, kann ein Problem auftreten, bei dem versucht wird, eine Einschränkung mit demselben Namen zweimal zu erstellen. Es wird empfohlen, alle explizit benannten Einschränkungen (ohne DEFAULT) oder alle systemdefinierten Namen (mit DEFAULT) zu verwenden.
  3. Bearbeiten Sie "model.xml" manuell, und benennen Sie die Einschränkung um, wobei der Name den Fehler in einen eindeutigen Namen aufweist. Diese Option sollte nur durchgeführt werden, wenn sie von der Microsoft-Unterstützung geleitet wird und ein Risiko von .bacpac-Korruption darstellt.

Stapelüberlauf-Ausnahme

Große T-SQL-Skripts mit vielen geschachtelten Anweisungen sind häufig die Ursache für zeitweilige oder dauerhafte Stapelüberlauf-Ausnahmen. In diesem Fall enthält die Fehlermeldung den Text Stack overflow und eine Stapelablaufverfolgung von:

Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.Visit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor.ExplicitVisit(Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.Accept(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)
Microsoft.SqlServer.TransactSql.ScriptDom.BinaryQueryExpression.AcceptChildren(Microsoft.SqlServer.TransactSql.ScriptDom.TSqlFragmentVisitor)

Für alle Befehle ist ein Parameter für SqlPackage verfügbar (/ThreadMaxStackSize:), der die maximale Stapelgröße für den Thread angibt, der den SqlPackage-Prozess ausführt. Der Standardwert wird durch die .NET-Version bestimmt, in der SqlPackage ausgeführt wird. Das Festlegen eines großen Werts kann sich auf die Gesamtleistung von SqlPackage auswirken. Die Erhöhung dieses Werts kann jedoch die Stapelüberlauf-Ausnahme beheben, die durch geschachtelte Anweisungen verursacht wird. Das Umgestalten des T-SQL-Codes wird empfohlen, um Stapelüberlauf-Ausnahmen nach Möglichkeit zu vermeiden, zur Problemumgehung kann jedoch der Parameter /ThreadMaxStackSize: verwendet werden.

Bei Verwendung des Parameters /ThreadMaxStackSize: empfiehlt es sich, wiederholte Vorgänge auf den niedrigsten Wert einzustellen, der die Stapelüberlauf-Ausnahme löst, sofern Leistungseinbußen festgestellt werden. Der Wert des Parameters wird in Megabyte (MB) angegeben. Beispielwerte zum Testen als Problemumgehung sind 10 und 100.

Diagnose

Protokolle sind für die Problembehandlung unbedingt erforderlich. Erfassen Sie die Diagnoseprotokolle in einer Datei mit dem Parameter /DiagnosticsFile:<filename>.

Zusätzliche leistungsbezogene Ablaufverfolgungsdaten können protokolliert werden, indem die Umgebungsvariable DACFX_PERF_TRACE=true vor der Ausführung von SqlPackage festgelegt wird. Verwenden Sie zum Festlegen dieser Umgebungsvariablen in PowerShell den folgenden Befehl:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Tipps zu Importaktionen

Bei Importen, die große Tabellen oder Tabellen mit vielen Indizes enthalten, kann die Leistung mithilfe von /p:RebuildIndexesOfflineForDataPhase=True oder /p:DisableIndexesForDataPhase=False verbessert werden. Diese Eigenschaften ändern den Indexneuerstellungsvorgang so, dass er offline bzw. nicht ausgeführt wird. Diese und weitere Eigenschaften stehen zum Optimieren des Vorgangs SqlPackage Import zur Verfügung.

Tipps zu Exportaktionen

Eine häufige Ursache für Leistungsbeeinträchtigungen beim Export sind nicht aufgelöste Objektverweise, die dazu führen, dass SqlPackage mehrfach versucht, das Objekt aufzulösen. Es wird z. B. eine Sicht definiert, die auf eine Tabelle verweist, die nicht mehr in der Datenbank vorhanden ist. Wenn das Exportprotokoll nicht aufgelöste Verweise enthält, sollten Sie erwägen, das Schema der Datenbank zu korrigieren, um die Exportleistung zu verbessern.

In Szenarios, in denen der Speicherplatz auf dem Betriebssystemdatenträger begrenzt ist und während des Exports aufgebraucht wird, ermöglicht die Verwendung von /p:TempDirectoryForTableData, dass die Daten für den Export auf einem alternativen Datenträger gepuffert werden. Der für diese Aktion erforderliche Speicherplatz kann sehr groß ausfallen und steht im Verhältnis zur vollständigen Größe der Datenbank. Diese und weitere Eigenschaften stehen zum Optimieren des Vorgangs SqlPackage Export zur Verfügung.

Bei einem Exportvorgang werden die Daten der Tabelle in der Bacpac-Datei komprimiert. Bei Verwendung von auf Fast, SuperFast oder NotCompressed festgelegtem /p:CompressionOption kann den Exportvorgang beschleunigt werden, während die BACPAC-Ausgabedatei weniger komprimiert wird.

Zum Abrufen des Datenbankschemas und von Daten beim Überspringen der Schemaüberprüfung führen Sie einen Export mit der Eigenschaft /p:VerifyExtraction=False aus. Unter Umständen wird ein ungültiger Export generiert, der nicht importiert werden kann.

Azure SQL-Datenbank

Die folgenden Tipps beziehen sich auf den Import oder Export in Azure SQL-Datenbank von einer Azure-VM:

  • Verwenden Sie für optimale Leistung eine Datenbank der Ebene „Unternehmenskritisch“ oder „Premium“.
  • Verwenden Sie SSD-Speicher auf der virtuellen Maschine.
  • Stellen Sie sicher, dass genügend Platz zum Entpacken des Bacpac vorhanden ist.
  • Führen Sie SqlPackage auf einer VM aus, die sich in derselben Region wie die Datenbank befindet.
  • Aktivieren Sie den beschleunigten Netzwerkbetrieb für die VM.

Weitere Informationen zum Verwenden eines PowerShell-Skripts zum Sammeln weiterer Informationen zu einem Importvorgang finden Sie unter Lektion Nr. 211: Überwachen des SQLPackage-Importprozesses.

Weitere Ressourcen

Der Blog zur Unterstützung von Azure-Datenbanken enthält viele Artikel zur Problembehandlung und Leistungsoptimierung für Azure SQL-Datenbank, darunter mehrere Artikel zu SqlPackage.

Zu den relevantesten Artikeln gehören:

Zugehöriger Inhalt