Řešení problémů a výkonu se SqlPackage

V některých scénářích operace SqlPackage trvá déle, než se čekalo, nebo se nedokončí. Tento článek popisuje některé často navrhované taktiky pro řešení potíží nebo zlepšení výkonu těchto operací. Při čtení konkrétní stránky dokumentace pro každou akci se doporučuje porozumět dostupným parametrům a vlastnostem, tento článek slouží jako výchozí bod při zkoumání operací SqlPackage.

Celková strategie

Obecně platí, že lepší výkon lze získat prostřednictvím verze .NET SqlPackage místo verze rozhraní .NET Framework nainstalované prostřednictvím DacFramework.msi.

Pokud nemůžete nainstalovat nástroj SqlPackage dotnet, který umožňuje spouštět příkazy SqlPackage z příkazového řádku v libovolném adresáři:

  1. Stáhnout zip pro SqlPackage v .NET 8 pro váš operační systém (Windows, macOS nebo Linux).
  2. Rozbalte archiv podle pokynů na stránce ke stažení.
  3. Otevřete příkazový řádek a změňte adresář (cd) do složky SqlPackage.

Používejte nejnovější dostupnou verzi SqlPackage, protože vylepšení výkonu a opravy chyb jsou pravidelně vydávány.

Nahrazení sqlpackage pro službu importu a exportu

Pokud jste se pokusili k importu nebo exportu databáze použít službu Import/Export, můžete stejnou operaci provést pomocí nástroje SqlPackage s větší kontrolou volitelných parametrů a vlastností. Blogový příspěvek Optimalizace importů BACPAC – SqlPackage Hotovo správně! vás provede postupem použití sqlPackage místo služby Import/Export pro .bacpac import.

Příklad příkazu importu:

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

V případě exportu je příklad příkazu:

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

Použijte vícefaktorovou autentizaci jako alternativu k uživatelskému jménu a heslu pro autentizaci pomocí Microsoft Entra. Nahraďte parametry uživatelského jména a hesla pro /ua:true a /tid:"contoso.onmicrosoft.com".

Diagnostics

Diagnostika chyb a neočekávaného chování v sqlPackage je podporována diagnostickými protokoly a diagnostickým balíčkem. Diagnostické protokoly jsou nezbytné pro řešení potíží a zaznamenávají se do souboru s parametrem /DiagnosticsFile:<filename>.

Úroveň detailu diagnostického výstupu je řízena pomocí parametru /DiagnosticsLevel . Použijte Information hodnoty a Verbose pro získání více podrobností.

Zaznamenávejte trasovací data související s výkonem nastavením proměnné prostředí DACFX_PERF_TRACE=true před spuštěním SqlPackage. Trasovací data zvětšují objem protokolu, proto je zahrnujte pouze při diagnostice problémů s výkonem. Pokud chcete nastavit tuto proměnnou prostředí v PowerShellu, použijte následující příkaz:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

V SqlPackage 162.5 a novějších verzích můžete vytvořit diagnostický balíček pro řešení problémů. Diagnostický balíček obsahuje verzi SqlPackage, spuštěný příkaz, informace o zdrojových a cílových databázových modelech a výstup příkazu. K vygenerování diagnostického balíčku použijte parametr /DiagnosticsPackageFile:<filename>.

Běžné problémy

Chyby časového limitu

Při problémech s časovým limitem použijte následující vlastnosti k ladění spojení mezi SqlPackage a SQL instancí:

  • /p:CommandTimeout=: Specifikuje časový limit příkazu během několika sekund při spuštění dotazu. Výchozí hodnota: 60
  • /p:DatabaseLockTimeout=: Určuje časový limit uzamčení databáze v sekundách. Použijte -1 k čekání na neomezenou dobu. Výchozí hodnota: 60
  • /p:LongRunningCommandTimeout=: Specifikuje časový limit v sekundách pro dlouho běžící příkaz. Výchozí hodnota 0, čeká neomezeně dlouho.

Spotřeba prostředků klienta

Pro příkazy exportu a extrakce SqlPackage předává data tabulky do dočasného adresáře, který je uloží do bufferu před zápisem do souboru BACPAC nebo DACPAC. Tato požadavek na úložiště může být velký a je relativní k plné velikosti dat k exportu. Zadejte alternativní dočasný adresář s vlastností /p:TempDirectoryForTableData=<path>.

SqlPackage kompiluje model schématu v paměti. U velkých databázových schémat může být požadavek na paměť na klientském stroji běžícím SqlPackage značný.

Nízká spotřeba prostředků serveru

SqlPackage ve výchozím nastavení nastaví maximální paralelismus serveru na hodnotu 8. Pokud si všimnete nízké spotřeby serverových zdrojů, zvýšení hodnoty parametru MaxParallelism může zlepšit výkon.

Token přístupu

Použití parametru /AccessToken: or /at: umožňuje tokenovou autentizaci pro SqlPackage, ale předání tokenu příkazu může být složité. Pokud v PowerShellu parsujete objekt přístupového tokenu, buď explicitně předejte řetězcovou hodnotu, nebo uzavřete odkaz na vlastnost tokenu do $(). Například:

$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

Pokud se sqlPackage nedaří připojit, server nemusí mít povolené šifrování nebo nakonfigurovaný certifikát nemusí být vystavený od důvěryhodné certifikační autority (například certifikátu podepsaného svým držitelem). Příkaz SqlPackage můžete změnit tak, aby se buď připojil bez šifrování, nebo důvěřoval certifikátu serveru. Osvědčeným postupem je zajistit, aby bylo možné navázat důvěryhodné šifrované připojení k serveru.

  • Připojení bez šifrování: /SourceEncryptConnection:False nebo /TargetEncryptConnection:False
  • Certifikát důvěryhodného serveru: /SourceTrustServerCertificate:True nebo /TargetTrustServerCertificate:True

Při připojení k SQL instanci můžete vidět jednu nebo více z následujících varovných zpráv, které naznačují, že parametry příkazového řádku mohou vyžadovat změny pro připojení k serveru:

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.

Další informace o změnách zabezpečení připojení v sqlPackage jsou k dispozici v Vylepšení zabezpečení připojení v SqlPackage 161.

Chyba akce importu 2714 pro omezení

Když provedete importní akci, můžete dostat chybu 2714, pokud objekt již existuje:

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

Tady jsou příčiny a řešení této chyby:

  1. Ověřte, že cíl, do kterého importujete, je prázdná databáze.
  2. Pokud má vaše databáze omezení, která používají DEFAULT atribut (kde SQL Server přiřadí omezení náhodné jméno) a explicitně pojmenované omezení, může být omezení se stejným názvem vytvořeno dvakrát. Použijte všechna explicitně pojmenovaná omezení (nepoužívejte DEFAULT), nebo použijte všechna systémově definovaná jména (použijte DEFAULT).
  3. Ručně upravte model.xml soubor a přejmenujte omezení podle jména, které chybu způsobuje, na jedinečné jméno. Tato možnost by měla být provedena pouze pokud k tomu vyzve podpora Microsoftu a nese riziko .bacpac poškození.

Výjimka přetečení zásobníku

Velké skripty T-SQL s mnoha vnořenými příkazy mohou způsobit občasné nebo trvalé výjimky z přetečení zásobníku. Když nastane tato podmínka, chybová zpráva obsahuje text Stack overflow a stackovou stopu:

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)

Parametr pro SqlPackage je k dispozici pro všechny příkazy, /ThreadMaxStackSize:, který určuje maximální velikost zásobníku pro vlákno, ve kterém běží proces SqlPackage. Výchozí hodnota je určená verzí .NET, na které běží SqlPackage. Nastavení vysoké hodnoty může ovlivnit celkový výkon SqlPackage. Zvýšení této hodnoty však může vyřešit výjimku přetečení zásobníku způsobenou vnořenými příkazy. Refaktorujte kód T-SQL tak, aby se pokud možno předešlo výjimkám typu stack overflow. Pokud nemůžete refaktorovat, použijte parametr /ThreadMaxStackSize: jako obcházení.

Když použijete parametr /ThreadMaxStackSize:, nastavte počet opakování na nejnižší hodnotu, která zabrání výjimce přetečení zásobníku, pokud zaznamenáte dopad na výkon. Hodnota parametru je v megabajtech (MB). Například můžete testovat hodnoty jako 10 a .100

Tipy k akcím importu

U importů, které obsahují velké tabulky nebo tabulky s mnoha indexy, může použití /p:RebuildIndexesOfflineForDataPhase=True nebo /p:DisableIndexesForDataPhase=False zlepšit výkon. Tyto vlastnosti upravují operaci opětovného sestavení indexu tak, aby probíhala offline, nebo aby k ní vůbec nedošlo. Tyto vlastnosti a další vlastnosti můžete použít k ladění operace SqlPackage Import .

Indexy jsou po importu zakázány

Pro efektivní načítání dat import deaktivuje neclusterované indexy před datovou fází a následně je znovu sestaví (výchozí /p:DisableIndexesForDataPhase=True chování). Pokud je import přerušen nebo selže po načtení dat, ale před dokončením přestavby, jeden nebo více neshlukovaných indexů může zůstat deaktivováno. Zakázáný index zůstává v metadatech, ale optimalizátor dotazů je ignoruje, což může způsobit pomalé dotazy po importu, který jinak vypadá jako úspěšný.

Pro nalezení deaktivovaných indexů zkontrolujte sloupec is_disabled v zobrazení katalogu sys.indexes :

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;

Pro opětovné povolení deaktivovaného indexu jej znovu sestavte pomocí ALTER INDEX. Použijte ALTER INDEX ALL ... REBUILD pro povolení všech deaktivovaných indexů v tabulce:

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

Pro více informací viz Povolit indexy a omezení.

Tipy pro akce exportu

Aby byl export transakční konzistentní, ujistěte se, že během exportu neprobíhá žádná zápisová aktivita, nebo že exportujete z transakčně konzistentní kopie vaší databáze. Pokud během importu obdržíte chyby ohledně omezení cizích klíčů, export nemusí být transakční konzistentní kvůli vloženým nebo aktualizovaným záznamům během exportu.

Výkon během exportu

Častou příčinou zhoršení výkonu během exportu jsou nevyřešené objektové reference. Tento problém způsobuje, že SqlPackage se opakovaně pokouší objekt vyřešit. Například je definován pohled, který odkazuje na tabulku, ale tabulka již v databázi neexistuje. Pokud se v protokolu exportu zobrazí nevyřešené odkazy, zvažte opravu schématu databáze, aby se zlepšil výkon exportu.

Během procesu exportu se data tabulky komprimují v souboru bacpac. Nastavení /p:CompressionOption na Fast, SuperFast, nebo NotCompressed může zlepšit rychlost exportního procesu při menším kompresi výstupního bacpac souboru.

Chcete-li získat schéma databáze a data při vynechání ověření schématu, proveďte Export s vlastností /p:VerifyExtraction=False. Může se vytvořit neplatný export, který se nedá importovat.

Místo na disku během exportu

V situacích, kdy je prostor na disku operačního systému omezený a během exportu dojde místo, použijte /p:TempDirectoryForTableData k dočasnému ukládání dat pro export na jiný disk. Požadované místo pro tuto akci může být velké a je relativní vzhledem k plné velikosti databáze. Operaci exportu SqlPackage můžete nastavit nastavením této a dalších vlastností.

Azure SQL Database

Následující tipy jsou specifické pro spuštění importu nebo exportu ve službě Azure SQL Database z virtuálního počítače Azure:

  • Pro zajištění nejlepšího výkonu používejte databázi úrovně Business Critical nebo Premium.
  • Použijte úložiště SSD na virtuálním počítači.
  • Ujistěte se, že je dostatek místa pro rozepnutí bacpaku.
  • Spusťte SqlPackage z virtuálního počítače ve stejné oblasti jako databáze.
  • Povolte akcelerované síťové služby na virtuálním počítači.

Pro více informací o použití PowerShell skriptu ke sběru informací o importní operaci viz Lesson Learned #211: Monitoring SQLPackage Import Process.

Další zdroje informací

Blog podpory služby Azure Database obsahuje mnoho článků o řešení potíží a ladění výkonu pro Azure SQL Database, včetně několika článků o sqlpackage.

Mezi nejdůležitější články patří:

Související obsah

  • Last updated on