Delen via

Problemen en prestaties met SqlPackage oplossen

  • Artikel

In sommige scenario's duurt het langer dan verwacht of mislukt de sqlPackage-bewerkingen. In dit artikel worden enkele veelgebruikte tactieken beschreven om de prestaties van deze bewerkingen op te lossen of te verbeteren. Het wordt aanbevolen om de specifieke documentatiepagina voor elke actie te lezen om de beschikbare parameters en eigenschappen beter te begrijpen. Dit artikel dient als startpunt voor het onderzoeken van SqlPackage-bewerkingen.

Algemene strategie

Als algemene richtlijn kunnen betere prestaties worden verkregen via de .NET-versie van SqlPackage in plaats van de .NET Framework-versie die via de DacFramework.msiis geïnstalleerd.

Als u het SqlPackage-dotnet-hulpprogramma niet kunt installeren, waarmee u SqlPackage-opdrachten kunt uitvoeren vanaf de commandoregel in een willekeurige map:

  1. Download de zip voor SqlPackage op .NET 8 voor uw besturingssysteem (Windows, macOS of Linux).
  2. Pak het archief uit zoals wordt aangegeven op de downloadpagina.
  3. Open een opdrachtprompt en wijzig de map (cd) in de map SqlPackage.

Het is belangrijk om de nieuwste beschikbare versie van SqlPackage te gebruiken, omdat prestatieverbeteringen en bugfixes regelmatig worden uitgebracht.

Vervang SqlPackage door de import-/exportservice

Als u de import-/exportservice hebt gebruikt om uw database te importeren of te exporteren, kunt u SqlPackage gebruiken om dezelfde bewerking uit te voeren met meer controle over optionele parameters en eigenschappen.

Voor Importeren is een voorbeeldopdracht:

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

Voor Exporteren is een voorbeeldopdracht:

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

Als alternatief voor gebruikersnaam en wachtwoord kunnen meervoudige verificatie worden gebruikt voor verificatie via Microsoft Entra-verificatie (voorheen Azure Active Directory) met meervoudige verificatie. Vervang de parameters voor gebruikersnaam en wachtwoord voor /ua:true en /tid:"yourdomain.onmicrosoft.com".

Diagnostisch pakket

In SqlPackage 162.5 en hoger kan een diagnostisch pakket worden gegenereerd om u te helpen bij het oplossen van problemen. Het diagnostische pakket bevat de SqlPackage-versie, de uitgevoerde opdracht en de uitvoer van de opdracht. Als u een diagnostisch pakket wilt genereren, gebruikt u de parameter /DiagnosticsFile:<filename>.

Veelvoorkomende problemen

Time-outfouten

Voor problemen met betrekking tot time-outs kunnen de volgende eigenschappen worden gebruikt om de verbinding tussen SqlPackage en het SQL-exemplaar af te stemmen:

  • /p:CommandTimeout=: hiermee geeft u de time-out van de opdracht in seconden op wanneer een query wordt uitgevoerd. Standaardwaarde: 60
  • /p:DatabaseLockTimeout=: Hiermee geeft u de time-out voor de databasevergrendeling in seconden op. -1 kan worden gebruikt om voor onbepaalde tijd te wachten, standaard: 60
  • /p:LongRunningCommandTimeout=: hiermee geeft u de time-out van de langlopende opdracht in seconden op. De standaardwaarde, 0, wordt gebruikt om voor onbepaalde tijd te wachten.

Verbruik van clientresources

Voor de opdrachten exporteren en extraheren worden tabelgegevens doorgegeven aan een tijdelijke map om te bufferen voordat ze naar het bacpac/dacpac-bestand worden geschreven. Deze opslagvereiste kan groot zijn en is relatief ten opzichte van de volledige grootte van de gegevens die moeten worden geëxporteerd. Geef een alternatieve tijdelijke map op met de eigenschap /p:TempDirectoryForTableData=<path>.

Het schemamodel wordt gecompileerd in het geheugen, dus voor grote databaseschema's kan de geheugenvereiste op de clientcomputer waarop SqlPackage wordt uitgevoerd aanzienlijk zijn.

Laag verbruik van serverresources

SqlPackage stelt standaard de maximale parallelle uitvoering van de server in op 8. Als u een laag verbruik van serverbronnen noteert, kan het verhogen van de waarde van de parameter MaxParallelism de prestaties verbeteren.

Toegangstoken

Met behulp van de parameter /AccessToken: of /at: kunt u verificatie op basis van tokens voor SqlPackage inschakelen, maar het doorgeven van het token aan de opdracht kan lastig zijn. Als u een toegangstokenobject in PowerShell parseert, geeft u de tekenreekswaarde expliciet door of verpakt u de verwijzing naar de tokeneigenschap in $(). Bijvoorbeeld:

$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)

Verbinding

Als SqlPackage geen verbinding kan maken, is versleuteling op de server mogelijk niet ingeschakeld of wordt het geconfigureerde certificaat mogelijk niet uitgegeven door een vertrouwde certificeringsinstantie (zoals een zelfondertekend certificaat). U kunt de opdracht SqlPackage wijzigen om verbinding te maken zonder versleuteling of om het servercertificaat te vertrouwen. De best practice is ervoor te zorgen dat er een vertrouwde versleutelde verbinding met de server tot stand kan worden gebracht.

  • Verbinding maken zonder versleuteling: /SourceEncryptConnection:False of /TargetEncryptConnection:False
  • Servercertificaat vertrouwen: /SourceTrustServerCertificate:True of /TargetTrustServerCertificate:True

U kunt een van de volgende waarschuwingsberichten zien wanneer u verbinding maakt met een SQL-exemplaar, waarmee wordt aangegeven dat opdrachtregelparameters wijzigingen kunnen vereisen om verbinding te maken met de server:

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.

Meer informatie over de wijzigingen in de verbindingsbeveiliging in SqlPackage is beschikbaar in Verbindingsbeveiligingsverbeteringen in SqlPackage 161.

Importactiefout 2714 voor beperking

Wanneer u een importactie uitvoert, krijgt u mogelijk fout 2714 als er al een object bestaat:

*** 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];

Hier volgen de oorzaken en oplossingen om deze fout te omzeilen:

  1. Controleer of het doel waarnaar u importeert een lege database is.
  2. Als uw database beperkingen heeft die gebruikmaken van het kenmerk DEFAULT (waarbij SQL Server een willekeurige naam toewijst aan de beperking) en een expliciet benoemde beperking, kan er twee keer een beperking met dezelfde naam worden gemaakt. Gebruik alle expliciet benoemde beperkingen (niet met DEFAULT) of alle door het systeem gedefinieerde namen (met DEFAULT).
  3. Bewerk de model.xml handmatig en hernoem de beperking met de naam die de fout veroorzaakt naar een unieke naam. Deze optie moet alleen worden uitgevoerd op aanwijzing van Microsoft-ondersteuning en vormt een risico op .bacpac-beschadiging.

Stack overflow-uitzondering

Grote T-SQL-scripts met veel ingebedde instructies zijn vaak de oorzaak van intermitterende of aanhoudende stack overflow-excepties. Als dit het geval is, bevat het foutbericht de tekst Stack overflow en een stacktrace van:

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)

Er is een parameter voor SqlPackage beschikbaar voor alle opdrachten, /ThreadMaxStackSize:, waarmee de maximale stackgrootte wordt opgegeven voor de thread waarop het SqlPackage-proces wordt uitgevoerd. De standaardwaarde wordt bepaald door de .NET-versie waarop SqlPackage wordt uitgevoerd. Het instellen van een grote waarde kan van invloed zijn op de algehele prestaties van SqlPackage, maar het verhogen van deze waarde kan de stack overflow-exceptie oplossen die wordt veroorzaakt door geneste instructies. Het herstructureren van de T-SQL-code wordt aanbevolen om zo mogelijk stackoverloop-uitzonderingen te voorkomen, maar de parameter /ThreadMaxStackSize: kan worden gebruikt als tijdelijke oplossing.

Wanneer u de parameter /ThreadMaxStackSize: gebruikt, is het raadzaam om het aantal herhaalde bewerkingen bij te stellen naar de laagste waarde die de stack-overloop-uitzondering oplost, als er een impact op de prestaties wordt opgemerkt. De waarde van de parameter is in megabytes (MB), voorbeeldwaarden voor testen als tijdelijke oplossing zijn 10 en 100.

Diagnostiek

Logboeken zijn essentieel voor het oplossen van problemen. Leg de diagnostische logboeken vast in een bestand met de parameter /DiagnosticsFile:<filename>.

Er kunnen meer prestatiegerelateerde traceringsgegevens worden vastgelegd door de omgevingsvariabele in te stellen DACFX_PERF_TRACE=true voordat SqlPackage wordt uitgevoerd. Gebruik de volgende opdracht om deze omgevingsvariabele in PowerShell in te stellen:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Tips voor actie importeren

Voor importbewerkingen die grote tabellen of tabellen met veel indexen bevatten, kan het gebruik van /p:RebuildIndexesOfflineForDataPhase=True of /p:DisableIndexesForDataPhase=False de prestaties verbeteren. Deze eigenschappen wijzigen de herbouwbewerking van de index zodat deze offline wordt uitgevoerd, of er helemaal niet plaatsvindt. Deze en andere eigenschappen zijn beschikbaar om de bewerking SqlPackage Import af te stemmen.

Actietips exporteren

Een veelvoorkomende oorzaak van prestatievermindering tijdens het exporteren is onopgeloste objectverwijzingen, waardoor SqlPackage meerdere keren probeert het object op te lossen. Er wordt bijvoorbeeld een weergave gedefinieerd die verwijst naar een tabel en de tabel niet meer in de database bestaat. Als niet-opgeloste verwijzingen worden weergegeven in het exportlogboek, kunt u overwegen het schema van de database te corrigeren om de exportprestaties te verbeteren.

In scenario's waarin de schijfruimte van het besturingssysteem beperkt is en tijdens de export opraakt, kan het gebruik van /p:TempDirectoryForTableData de gegevens voor export bufferen op een alternatieve schijf. De benodigde ruimte voor deze actie kan groot zijn en is relatief ten opzichte van de volledige grootte van de database. Die en andere eigenschappen zijn beschikbaar om de SqlPackage Export--bewerking af te stemmen.

Tijdens een exportproces worden de tabelgegevens gecomprimeerd in het bacpac-bestand. Het gebruik van /p:CompressionOption ingesteld op Fast, SuperFastof NotCompressed kan de snelheid van het exportproces verbeteren terwijl het uitvoerbestand minder wordt gecomprimeerd.

Als u het databaseschema en de gegevens wilt ophalen tijdens het overslaan van de schemavalidatie, voert u een Export- uit met de eigenschap /p:VerifyExtraction=False. Er kan een ongeldige export worden geproduceerd die niet kan worden geïmporteerd.

Azure SQL Database

De volgende tips zijn specifiek voor het uitvoeren van importeren of exporteren met Azure SQL Database vanaf een virtuele Azure-machine (VM):

  • Gebruik de database Bedrijfskritiek of Premium-laag voor de beste prestaties.
  • Gebruik SSD-opslag op de virtuele machine.
  • Zorg ervoor dat er voldoende ruimte is om de rugzak open te ritsen.
  • Voer SqlPackage uit vanaf een virtuele machine in dezelfde regio als de database.
  • Schakel versneld netwerken in op de VIRTUELE machine.

Zie Lesson Learned #211: SqlPackage-importproces bewakenvoor meer informatie over het gebruik van een PowerShell-script voor het verzamelen van meer informatie over een importbewerking.

Meer bronnen

De Azure Database Support Blog bevat veel artikelen over het oplossen van problemen en het afstemmen van prestaties voor Azure SQL Database, waaronder verschillende artikelen over SqlPackage.

Enkele van de meest relevante artikelen zijn:

Verwante inhoud