Problemen en prestaties met SqlPackage oplossen

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 je de SqlPackage dotnet-tool niet kunt installeren, waarmee je SqlPackage-commando's vanuit de opdrachtprompt in elke map kunt uitvoeren:

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

Gebruik de meest recente beschikbare versie van SqlPackage, want er worden regelmatig prestatieverbeteringen en bugfixes 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. Het blogbericht BACPAC-import optimaliseren - SqlPackage Done Right! doorloopt de stappen voor het gebruik van SqlPackage in plaats van de Import/Export-service voor een .bacpac import.

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>

Gebruik multifactorauthenticatie als alternatief voor gebruikersnaam en wachtwoord om te authenticeren met Microsoft Entra-authenticatie. Vervang de parameters voor gebruikersnaam en wachtwoord voor /ua:true en /tid:"contoso.onmicrosoft.com".

Diagnostics

Het diagnosticeren van fouten en onverwacht gedrag in SqlPackage wordt ondersteund door diagnostische logboeken en een diagnostisch pakket. De diagnostische logboeken zijn essentieel voor het oplossen van problemen en worden vastgelegd in een bestand met de parameter /DiagnosticsFile:<filename>.

Beheer het detailniveau in diagnostische output via de /DiagnosticsLevel parameter. Gebruik de Information en Verbose waarden om meer details te krijgen.

Log prestatiegerelateerde tracegegevens door de omgevingsvariabele DACFX_PERF_TRACE=true in te stellen voordat je SqlPackage uitvoert. De trace-gegevens verhogen de loguitvoer, dus neem deze alleen mee bij het diagnosticeren van prestatieproblemen. Gebruik de volgende opdracht om deze omgevingsvariabele in PowerShell in te stellen:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

In SqlPackage 162.5 en later kun je een diagnostisch pakket genereren om te helpen bij het oplossen van problemen. Het diagnostische pakket bevat de SqlPackage-versie, de opdracht uitgevoerd, informatie over de bron- en doeldatabasemodellen en de uitvoer van de opdracht. Als u een diagnostisch pakket wilt genereren, gebruikt u de parameter /DiagnosticsPackageFile:<filename>.

Algemene problemen

Time-outfouten

Voor time-outproblemen gebruik je de volgende eigenschappen om de verbinding tussen SqlPackage en de SQL-instantie af te stemmen:

  • /p:CommandTimeout=: Specificeert de commando-timeout in seconden wanneer een query wordt uitgevoerd. Standaardwaarde: 60
  • /p:DatabaseLockTimeout=: Hiermee geeft u de time-out voor de databasevergrendeling in seconden op. Gebruik -1 dit om voor onbepaalde tijd te wachten. Standaardwaarde: 60
  • /p:LongRunningCommandTimeout=: hiermee geeft u de time-out van de langlopende opdracht in seconden op. De standaardwaarde, 0, wacht oneindig.

Verbruik van clientresources

Voor de export- en extractiecommando's stuurt SqlPackage tabelgegevens door naar een tijdelijke map om te bufferen voordat deze worden geschreven naar het BACPAC- of DACPAC-bestand. Deze opslagbehoefte kan groot zijn en is relatief afhankelijk van de volledige omvang van de te exporteren data. Geef een alternatieve tijdelijke map op met de eigenschap /p:TempDirectoryForTableData=<path>.

SqlPackage compileert het schemamodel in het geheugen. Voor grote databaseschema's kan de geheugenbehoefte op de clientmachine die SqlPackage draait aanzienlijk zijn.

Laag verbruik van serverresources

SqlPackage stelt standaard de maximale parallelle uitvoering van de server in op 8. Als je merkt dat het verbruik van serverbronnen laag is, kan het verhogen van de waarde van de MaxParallelism parameter de prestaties verbeteren.

Toegangstoken

Het gebruik van de /AccessToken: or-parameter /at: maakt tokengebaseerde authenticatie voor SqlPackage mogelijk, maar het doorgeven van het token aan het commando kan lastig zijn. Als je een access token-object in PowerShell pars, geef dan expliciet de stringwaarde door of wikkel de referentie naar de tokeneigenschap in $(). Voorbeeld:

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

Connection

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

Je kunt een of meer van de volgende waarschuwingsberichten zien bij het verbinden met een SQL-instantie, die aangeven dat commandoregelparameters mogelijk wijzigingen 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 je een importactie uitvoert, kun je foutmelding 2714 krijgen 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 je database constraints heeft die het DEFAULT attribuut gebruiken (waarbij SQL Server een willekeurige naam aan de constraint toewijst) en een expliciet benoemde constraint, kan een constraint met dezelfde naam twee keer worden aangemaakt. Gebruik alle expliciet benoemde constraints (gebruik niet DEFAULT), of gebruik alle systeemgedefinieerde namen (gebruik DEFAULT).
  3. Bewerk het model.xml bestand 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.

Stackoverloop-uitzondering

Grote T-SQL-scripts met veel geneste statements kunnen intermitterende of persistente stack overflow-uitzonderingen veroorzaken. Wanneer deze voorwaarde zich voordoet, bevat het foutbericht de tekst Stack overflow en een stacktrace:

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 hoge waarde kan de algehele prestaties van SqlPackage beïnvloeden. Het verhogen van deze waarde kan echter de stack overflow-uitzondering veroorzaakt door geneste statements oplossen. Refactoriseer de T-SQL-code om stack overflow-uitzonderingen waar mogelijk te vermijden. Als je niet kunt refactoren, gebruik dan de /ThreadMaxStackSize: parameter als een workaround.

Wanneer je de /ThreadMaxStackSize: parameter gebruikt, stem herhaalde bewerkingen af op de laagste waarde die de stack overflow-uitzondering oplost als je een prestatie-impact merkt. De waarde van de parameter is in megabytes (MB). Je kunt bijvoorbeeld waarden als 10 en 100testen.

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. Je kunt deze eigenschappen en andere eigenschappen gebruiken om de SqlPackage Import-operatie af te stemmen.

Indexen worden uitgeschakeld na een import

Om data efficiënt te laden, schakelt een import niet-geclusterde indexen uit vóór de datafase en bouwt ze daarna opnieuw op (het standaardgedrag /p:DisableIndexesForDataPhase=True ). Als de import wordt onderbroken of mislukt nadat de data is geladen maar voordat de herbouw is voltooid, kunnen één of meer niet-geclusterde indexen uitgeschakeld blijven. Een uitgeschakelde index blijft in metadata, maar de query-optimizer negeert het, wat na een import trage queries kan veroorzaken die anders lijkt te slagen.

Om uitgeschakelde indexen te vinden, controleer de is_disabled kolom in de sys.indexes catalogusweergave:

SELECT OBJECT_SCHEMA_NAME(object_id) AS schema_name,
       OBJECT_NAME(object_id) AS table_name,
       name AS index_name
FROM sys.indexes
WHERE is_disabled = 1;

Om een uitgeschakelde index weer in te schakelen, bouw je deze opnieuw op met ALTER INDEX. Gebruik ALTER INDEX ALL ... REBUILD om alle uitgeschakelde indexen in een tabel in te schakelen:

ALTER INDEX ALL ON <schema>.<table> REBUILD;

Voor meer informatie, zie Indexen en beperkingen inschakelen.

Exporteer actietips

Om een export transactioneel consistent te maken, zorg ervoor dat er tijdens de export geen schrijfactiviteit plaatsvindt, of dat je exporteert vanuit een transactioneel consistente kopie van je database. Als je fouten ontvangt over vreemde sleutelbeperkingen tijdens een import, kan de export niet transactioneel consistent zijn vanwege ingevoegde of bijgewerkte records tijdens het exportproces.

Prestaties tijdens het exporteren

Een veelvoorkomende oorzaak van prestatieverlies tijdens export zijn onopgeloste objectreferenties. Dit probleem zorgt ervoor dat SqlPackage meerdere keren probeert het object op te lossen. Bijvoorbeeld, er wordt een view gedefinieerd die naar een tabel verwijst, maar die tabel bestaat niet meer in de database. Als niet-opgeloste verwijzingen worden weergegeven in het exportlogboek, kunt u overwegen het schema van de database te corrigeren om de exportprestaties te verbeteren.

Tijdens een exportproces worden de tabelgegevens gecomprimeerd in het bacpac-bestand. Door /p:CompressionOption in te stellen op Fast, SuperFast of NotCompressed kan de snelheid van het exportproces verbeteren, waarbij het BACPAC-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.

Schijfruimte tijdens het exporteren

In scenario's waarin de OS-schijfruimte beperkt is en opraakt tijdens de export, gebruik /p:TempDirectoryForTableData je deze om de data voor export op een alternatieve schijf te bufferen. De benodigde ruimte voor deze actie kan groot zijn en is relatief ten opzichte van de volledige grootte van de database. Je kunt de SqlPackage Export-operatie afstemmen door deze en andere eigenschappen in te stellen.

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 Business Critical- of de Premium-laag database voor de beste prestaties.
  • Gebruik SSD-opslag op de virtuele machine.
  • Zorg ervoor dat er voldoende ruimte is om de bacpac open te ritsen.
  • Voer SqlPackage uit vanaf een virtuele machine in dezelfde regio als de database.
  • Schakel versneld netwerken in op de VIRTUELE machine.

Voor meer informatie over het gebruik van een PowerShell-script om details over een importoperatie te verzamelen, zie Lesson Learned #211: Monitoring van het SQLPackage Importproces.

Meer middelen

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

  • Last updated on