Dela via

Felsöka problem och prestanda med SqlPackage

  • Artikel

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 verktyget SqlPackage dotnet, vilket gör det möjligt att köra SqlPackage-kommandon från kommandotolken i valfri katalog:

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

Det är viktigt att använda den senaste tillgängliga versionen av SqlPackage eftersom prestandaförbättringar och felkorrigeringar 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.

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>

Alternativt till användarnamn och lösenord kan multifaktorautentisering användas för att autentisera via Microsoft Entra-autentisering (tidigare Azure Active Directory) med multifaktorautentisering. Ersätt parametrarna användarnamn och lösenord för /ua:true och /tid:"yourdomain.onmicrosoft.com".

Diagnostik

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

Detaljnivån i diagnostikutdata styrs via parametern /DiagnosticsLevel. Värden för Information och Verbose är användbara för att få mer information.

Prestandarelaterade spårningsdata kan loggas genom att ange miljövariabeln DACFX_PERF_TRACE=true innan du kör SqlPackage. Spårningsdata ökar loggoutputen, så inkludera det endast vid diagnostisering av prestanda-utmaningar. 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 ett diagnostikpaket genereras för 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-fel

För problem som rör tidsgränser kan följande egenskaper användas för att justera anslutningen mellan SqlPackage och SQL-instansen:

  • /p:CommandTimeout=: Anger kommandotidsgränsen i sekunder när en fråga körs. Standard: 60
  • /p:DatabaseLockTimeout=: Anger tidsgränsen för databaslåset i sekunder. -1 kan användas för att vänta på obestämd tid, standard: 60
  • /p:LongRunningCommandTimeout=: Anger tidsgränsen för långvariga kommandon i sekunder. Standardvärdet 0 används för att vänta på obestämd tid.

Förbrukning av klientresurser

För export- och extraheringskommandona skickas tabelldata till en tillfällig katalog som ska buffra innan de skrivs till bacpac/dacpac-filen. Det här lagringskravet kan vara stort och är i förhållande till den fullständiga storleken på de data som ska exporteras. Ange en alternativ tillfällig katalog med egenskapen /p:TempDirectoryForTableData=<path>.

Schemamodellen kompileras i minnet, så för stora databasscheman kan minnesbehovet på klientdatorn som kör SqlPackage vara betydande.

Låg serverresursförbrukning

Som standard anger SqlPackage den maximala serverparallelliteten till 8. Om du noterar låg serverresursförbrukning kan du förbättra prestandan genom att öka värdet för parametern MaxParallelism.

Åtkomsttoken

Att använda parametern /AccessToken: eller /at: möjliggör tokenbaserad autentisering för SqlPackage, men det kan vara svårt att skicka token till kommandot. Om du parsar ett objekt för åtkomsttoken i PowerShell skickar du antingen strängvärdet explicit eller omsluter referensen till tokenegenskapen 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)

Samband

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 något 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 finns:

*** 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 databasen har begränsningar som använder standardattributet (där SQL Server tilldelar villkoret ett slumpmässigt namn) och en uttryckligen namngiven begränsning kan en begränsning med samma namn skapas två gånger. Du bör använda alla uttryckligen namngivna begränsningar (inte använda STANDARD) eller alla systemdefinierade namn (använda STANDARD).
  3. Redigera model.xml manuellt och ändra namnet på den begränsning som upplever 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 kapslade instruktioner är ofta orsaken till tillfälliga eller beständiga stacköverflödesfel. I sådana fall kommer felmeddelandet att innehålla texten Stack overflow och en stackspårning som visar:

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 ange ett stort värde kan påverka den övergripande prestandan för SqlPackage, men om du ökar det här värdet kan det lösa stacköverflödets undantag som orsakas av kapslade instruktioner. Refaktorisering av T-SQL-koden rekommenderas för att undvika stacköverflödesundantag om möjligt, men parametern /ThreadMaxStackSize: kan användas som en lösning.

När du använder parametern /ThreadMaxStackSize: rekommenderar vi att du justerar upprepade åtgärder till det lägsta värde som löser stacköverflödesfelet om prestandapåverkan noteras. Värdet för parametern finns i megabyte (MB), exempelvärden för testning som en lösning: 10 och 100.

Tips för importåtgärd

För importer som innehåller stora tabeller eller tabeller med många index kan användningen av /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. Dessa och andra egenskaper är tillgängliga för att justera åtgärden SqlPackage Import.

Tips för exportåtgärder

En vanlig orsak till prestandaförsämring vid export är olösta objektreferenser, vilket gör att SqlPackage försöker lösa objektet flera gånger. Till exempel definieras en vy som refererar till en tabell och 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.

I scenarier där os-diskutrymmet är begränsat och tar slut under exporten gör användningen av /p:TempDirectoryForTableData att data för export kan bufferas på en alternativ disk. Utrymmet som krävs för den här åtgärden kan vara stort och är relativt databasens fulla storlek. Det och andra egenskaper är tillgängliga för att justera åtgärden SqlPackage Export.

Under en exportprocess komprimeras tabelldata i bacpac-filen. Användningen av /p:CompressionOption inställd på Fast, SuperFasteller NotCompressed kan förbättra exportprocesshastigheten samtidigt som bacpac-utdatafilen komprimeras 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.

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

Mer information om hur du använder ett PowerShell-skript för att samla in mer information om en importåtgärd finns i Lesson Learned #211: Monitoring 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