Felsöka problem och prestanda med SqlPackage

I vissa scenarier tar SqlPackage-åtgärder längre tid än förväntat eller misslyckas med att slutföra. Den här artikeln beskriver några vanliga taktiker för att felsöka eller förbättra prestanda för dessa åtgärder. Det rekommenderas att läsa den specifika dokumentationssidan för varje åtgärd för att förstå tillgängliga parametrar och egenskaper, men den här artikeln fungerar som en utgångspunkt för att utforska SqlPackage-åtgärder.

Övergripande strategi

Som allmän riktlinje kan du få bättre prestanda via den .NET-versionen av SqlPackage i stället för den .NET Framework-version som installeras via DacFramework.msi.

Om du inte kan installera SqlPackage dotnet-verktyget, som gör det möjligt för dig att köra SqlPackage-kommandon från kommandoprompten i vilken katalog som helst:

  1. Ladda ned zip för SqlPackage på .NET 8 för ditt operativsystem (Windows, macOS eller Linux).
  2. Packa upp arkivet enligt instruktionerna på nedladdningssidan.
  3. Öppna en kommandotolk och ändra katalogen (cd) till mappen SqlPackage.

Använd den senaste tillgängliga versionen av SqlPackage, eftersom prestandaförbättringar och buggfixar släpps regelbundet.

Ersätt SqlPackage med import-/exporttjänsten

Om du försökte använda import-/exporttjänsten för att importera eller exportera databasen kan du använda SqlPackage för att utföra samma åtgärd med mer kontroll över valfria parametrar och egenskaper. Blogginlägget Optimizeing BACPAC Imports – SqlPackage Done Right! går igenom stegen för att använda SqlPackage i stället för import-/exporttjänsten för en .bacpac import.

För Import är ett exempelkommando:

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

För Export är ett exempelkommando:

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

Använd multifaktorautentisering som ett alternativ till användarnamn och lösenord för att autentisera med Microsoft Entra-autentisering. Ersätt parametrarna användarnamn och lösenord för /ua:true och /tid:"contoso.onmicrosoft.com".

Diagnostics

Diagnostisering av fel och oväntat beteende i SqlPackage stöds av diagnostikloggar och ett diagnostikpaket. Diagnostikloggarna är viktiga för felsökning och samlas in i en fil med parametern /DiagnosticsFile:<filename>.

Kontrollera detaljnivån i diagnostiska utdata via parametern /DiagnosticsLevel . Använd värdena Verbose och Information för att få mer information.

Logga prestandarelaterad spårningsdata genom att sätta miljövariabeln DACFX_PERF_TRACE=true innan du kör SqlPackage. Spårningsdata ökar loggutdatan, så inkludera den endast vid diagnos av prestandautmaningar. Om du vill ange den här miljövariabeln i PowerShell använder du följande kommando:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

I SqlPackage 162.5 och senare kan du generera ett diagnostiskt paket för att hjälpa till med felsökning. Diagnostikpaketet innehåller SqlPackage-versionen, kommandot som körs, information om käll- och måldatabasmodellerna och utdata från kommandot. Om du vill generera ett diagnostikpaket använder du parametern /DiagnosticsPackageFile:<filename>.

Vanliga problem

Timeout-felmeddelanden

För timeout-problem, använd följande egenskaper för att justera anslutningen mellan SqlPackage och SQL-instansen:

  • /p:CommandTimeout=: Anger tidsgränsen för kommandot i sekunder när en fråga körs. Förval: 60
  • /p:DatabaseLockTimeout=: Anger tidsgränsen för databaslåset i sekunder. Använd -1 för att vänta på obestämd tid. Förval: 60
  • /p:LongRunningCommandTimeout=: Anger tidsgränsen för långvariga kommandon i sekunder. Standardvärdet, 0, väntar på obestämd tid.

Förbrukning av klientresurser

För export- och extraheringskommandona skickar SqlPackage tabelldata till en tillfällig katalog för att buffra innan det skrivs till BACPAC- eller DACPAC-filen. Detta lagringsbehov kan vara stort och är relativt till den fulla storleken på datan som ska exporteras. Ange en alternativ tillfällig katalog med egenskapen /p:TempDirectoryForTableData=<path>.

SqlPackage kompilerar schemamodellen i minnet. För stora databasscheman kan minneskravet på klientmaskinen som kör SqlPackage vara betydande.

Låg serverresursförbrukning

Som standard anger SqlPackage den maximala serverparallelliteten till 8. Om du märker låg resursförbrukning kan en ökning av MaxParallelism parameterns värde förbättra prestandan.

Åtkomsttoken

Att använda or-parametern /AccessToken:/at: möjliggör tokenbaserad autentisering för SqlPackage, men att skicka token till kommandot kan vara knepigt. Om du tolkar ett access-tokenobjekt i PowerShell, antingen skickar du uttryckligen strängvärdet eller lindar referensen till token-egenskapen i $(). Till exempel:

$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

Om SqlPackage inte kan ansluta kanske servern inte har kryptering aktiverat eller så kanske det konfigurerade certifikatet inte utfärdas från en betrodd certifikatutfärdare (till exempel ett självsignerat certifikat). Du kan ändra SqlPackage-kommandot till att antingen ansluta utan kryptering eller att lita på servercertifikatet. Det bästa praxis är att säkerställa att en betrodd krypterad anslutning till servern kan upprättas.

  • Anslut utan kryptering: /SourceEncryptConnection:False eller /TargetEncryptConnection:False
  • Betrodda servercertifikat: /SourceTrustServerCertificate:True eller /TargetTrustServerCertificate:True

Du kan se ett eller flera av följande varningsmeddelanden när du ansluter till en SQL-instans, vilket indikerar att kommandoradsparametrar kan kräva ändringar för att ansluta till servern:

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.

Mer information om anslutningssäkerhetsändringarna i SqlPackage finns i Förbättringar av anslutningssäkerhet i SqlPackage 161.

Importåtgärdsfel 2714 för begränsning

När du utför en importåtgärd kan du få fel 2714 om ett objekt redan existerar:

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

Här är orsakerna och lösningarna för att kringgå det här felet:

  1. Kontrollera att målet som du importerar till är en tom databas.
  2. Om din databas har begränsningar som använder attributet DEFAULT (där SQL Server tilldelar ett slumpmässigt namn till begränsningen) och en explicit namngiven begränsning, kan en begränsning med samma namn skapas två gånger. Använd alla explicit namngivna begränsningar (använd inte DEFAULT), eller använd alla systemdefinierade namn (använd DEFAULT).
  3. Redigera model.xml filen manuellt och byt namn på begränsningen med namnet som orsakar felet till ett unikt namn. Det här alternativet bör endast utföras om det instrueras av Microsofts support och utgör en risk för .bacpac-korruption.

Stacköverflödesundantag

Stora T-SQL-skript med många nästlade satser kan orsaka intermittenta eller persistenta stack overflow-undantag. När detta villkor uppstår, innehåller felmeddelandet texten Stack overflow och en stackspårning:

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)

En parameter för SqlPackage är tillgänglig för alla kommandon, /ThreadMaxStackSize:, som anger den maximala stackstorleken för den tråd som kör SqlPackage-processen. Standardvärdet bestäms av .NET-versionen som kör SqlPackage. Att sätta ett stort värde kan påverka den övergripande prestandan för SqlPackage. Dock kan en ökning av detta värde lösa stack overflow-undantaget som orsakas av nästlade satser. Omstrukturera T-SQL-koden för att undvika stack overflow-undantag när det är möjligt. Om du inte kan refaktorera, använd parametern /ThreadMaxStackSize: som en lösning.

När du använder parametern /ThreadMaxStackSize: , justera upprepade operationer till det lägsta värdet som löser stack-överflödesundantaget om du märker en prestandapåverkan. Parameterns värde är i megabyte (MB). Till exempel kan du testa värden som 10 och 100.

Tips för importåtgärd

För importer som innehåller stora tabeller eller tabeller med många index kan man använda /p:RebuildIndexesOfflineForDataPhase=True eller /p:DisableIndexesForDataPhase=False förbättra prestandan. Dessa egenskaper modifierar indexåterskapandeoperationen så att den sker offline eller inte alls sker. Du kan använda dessa egenskaper och andra egenskaper för att finjustera SqlPackage Import-operationen .

Index inaktiveras efter en import

För att läsa in data effektivt inaktiverar en import icke-klustrade index före datafasen och bygger om dem efteråt (standardbeteendet /p:DisableIndexesForDataPhase=True). Om importen avbryts eller misslyckas efter dataladdningen men innan ombyggnaden är klar kan ett eller flera icke-klustrade index förbli inaktiverade. Ett inaktiverat index stannar kvar i metadata, men frågeoptimeraren ignorerar det, vilket kan orsaka långsamma frågor efter en import som annars verkar lyckas.

För att hitta inaktiverade index, kontrollera kolumnen is_disabled i sys.indexes katalogvy:

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;

För att återaktivera ett inaktiverat index, bygg om det med ALTER INDEX. Använd ALTER INDEX ALL ... REBUILD för att aktivera alla inaktiverade index i en tabell:

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

För mer information, se Aktivera index och begränsningar.

Tips för exportåtgärder

För att en export ska vara transaktionsmässigt konsistent, se till att ingen skrivaktivitet sker under exporten, eller att du exporterar från en transaktionellt konsekvent kopia av din databas. Om du får fel om främmande nyckelbegränsningar under en import kan exporten vara transaktionsmässigt inkonsekvent på grund av insatta eller uppdaterade poster under exportprocessen.

Prestanda vid export

En vanlig orsak till prestandaförsämring under export är olösta objektreferenser. Detta problem gör att SqlPackage försöker lösa objektet flera gånger. Till exempel definieras en vy som refererar till en tabell men tabellen finns inte längre i databasen. Om olösta referenser visas i exportloggen bör du överväga att korrigera schemat för databasen för att förbättra exportprestandan.

Under en exportprocess komprimeras tabelldata i bacpac-filen. Att ställa in /p:CompressionOption till Fast, SuperFast, eller NotCompressed kan förbättra exportprocessens hastighet samtidigt som man komprimerar utdata bacpac-filen mindre.

Om du vill hämta databasschemat och data utan att utföra schemaverifieringen utför du en Export med egenskapen /p:VerifyExtraction=False. En ogiltig export kan skapas som inte kan importeras.

Diskutrymme under exportprocessen

I situationer där operativsystemets diskutrymme är begränsat och tar slut under exporten, använd /p:TempDirectoryForTableData den för att buffra data för export på en alternativ disk. Utrymmet som krävs för den här åtgärden kan vara stort och är relativt databasens fulla storlek. Du kan justera SqlPackage Export-operationen genom att sätta denna och andra egenskaper.

Azure SQL Database

Följande tips är specifika för att köra import eller export mot Azure SQL Database från en virtuell Azure-dator (VM):

  • Använd business critical- eller Premium-nivådatabasen för bästa prestanda.
  • Använd SSD-lagring på den virtuella datorn.
  • Se till att det finns tillräckligt med plats för att packa upp bacpac.
  • Kör SqlPackage från en virtuell dator i samma region som databasen.
  • Aktivera accelererat nätverk på den virtuella datorn.

För mer information om hur man använder ett PowerShell-skript för att samla in detaljer om en importoperation, se Lesson Learned #211: Övervakning av SQLPackage Import Process.

Fler resurser

Supportbloggen för Azure Database innehåller många artiklar om felsökning och prestandajustering för Azure SQL Database, inklusive flera artiklar om SqlPackage.

Några av de mest relevanta artiklarna är:

Relaterat innehåll

  • Last updated on