Az SqlPackage hibáinak és teljesítményének elhárítása

Bizonyos esetekben az SqlPackage-műveletek a vártnál hosszabb időt vesznek igénybe, vagy nem fejeződnek be. Ez a cikk néhány gyakran javasolt taktikát ismertet ezeknek a műveleteknek a hibaelhárítására vagy teljesítményének javítására. A rendelkezésre álló paraméterek és tulajdonságok megismeréséhez ajánlott elolvasni az egyes műveletek dokumentációs oldalát, ez a cikk kiindulópontként szolgál az SqlPackage-műveletek vizsgálatához.

Általános stratégia

Általános útmutatóként jobb teljesítmény érhető el az SqlPackage .NET-verziójával a DacFramework.msitelepített .NET-keretrendszerverzió helyett.

Ha nem tudod telepíteni a SqlPackage dotnet eszközt, amely lehetővé teszi, hogy bármelyik könyvtárban végrehajtsd a SqlPackage parancsokat:

  1. Töltse le az SqlPackage zip-jének letöltését a .NET 8-on az operációs rendszerhez (Windows, macOS vagy Linux).
  2. Bontsd ki az archívumot a letöltési oldalon az utasítások szerint.
  3. Nyisson meg egy parancssort, és módosítsa a könyvtárat (cd) az SqlPackage mappára.

Használd a SqlPackage legújabb elérhető verzióját, mivel teljesítményjavítások és hibajavítások rendszeresen jelennek meg.

Az SqlPackage helyettesítése az importálási/exportálási szolgáltatáshoz

Ha az importálási/exportálási szolgáltatással próbálta importálni vagy exportálni az adatbázist, az SqlPackage használatával ugyanezt a műveletet hajthatja végre az opcionális paraméterek és tulajdonságok nagyobb szabályozásával. A BACPAC-importálás optimalizálása – SqlPackage Done Right! blogbejegyzés végigvezeti az SqlPackage importálási/exportálási szolgáltatás helyett való használatának lépésein .bacpac .

Importálás esetén egy példaparancs a következő:

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

Exportálás esetén egy példaparancs a következő:

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

Használj többfaktoros hitelesítést alternatívaként a felhasználónév és jelszó helyett, hogy Microsoft Entra hitelesítéssel autentikálj. Cserélje le a felhasználónév és a jelszó paramétereit /ua:true és /tid:"contoso.onmicrosoft.com".

Diagnostics

Az SqlPackage hibáinak és váratlan viselkedésének diagnosztizálása diagnosztikai naplókkal és diagnosztikai csomagokkal támogatott. A diagnosztikai naplók elengedhetetlenek a hibaelhárításhoz, és a /DiagnosticsFile:<filename> paraméterrel rendelkező fájlba vannak rögzítve.

A paraméteren keresztül irányítja a diagnosztikai kimenet /DiagnosticsLevel részletességét. Használd az Information és Verbose értékeket, hogy több részletet szerezz.

A teljesítményhez kapcsolódó nyomkövetési adatokat logold a környezeti változó beállításával DACFX_PERF_TRACE=true a SqlPackage futtatása előtt. A nyomkövetési adatok növelik a napló kimenetét, ezért csak teljesítményproblémák diagnosztizálásakor vegyék figyelembe. A környezeti változó PowerShellben való beállításához használja a következő parancsot:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

A SqlPackage 162.5 és újabb verziókban diagnosztikai csomagot lehet létrehozni, amely segít a hibakeresésben. A diagnosztikai csomag tartalmazza az SqlPackage verzióját, a végrehajtott parancsot, a forrás- és céladatbázis-modellekre vonatkozó információkat, valamint a parancs kimenetét. Diagnosztikai csomag létrehozásához használja a /DiagnosticsPackageFile:<filename> paramétert.

Gyakori problémák

Időtúllépési hibák

Időtúllépési problémák esetén a következő tulajdonságokat használd a SqlPackage és az SQL példány közötti kapcsolat beállításához:

  • /p:CommandTimeout=: Megadja a parancs időtúllépését másodpercekben, amikor egy lekérdezés fut. Alapértelmezett: 60
  • /p:DatabaseLockTimeout=: Az adatbázis zárolási időkorlátját adja meg másodpercben. A -1 használatával korlátlan ideig várakozhat. Alapértelmezett: 60
  • /p:LongRunningCommandTimeout=: Meghatározza a hosszú ideig futó parancs időkorlátját másodpercekben. Az alapértelmezett érték, 0, korlátlan ideig vár.

Ügyfélerőforrás-felhasználás

Az exportálási és kinyerési parancsokhoz a SqlPackage átadja a táblaadatokat egy ideiglenes könyvtárba, hogy pufferelje, mielőtt a BACPAC vagy DACPAC fájlba írná őket. Ez a tárolási igény nagy lehet, és az exportálandó adatok teljes méretéhez viszonyítható. Adjon meg egy másik ideiglenes könyvtárat a /p:TempDirectoryForTableData=<path>tulajdonsággal.

A SqlPackage a sémamodellt a memóriában lefordítja. Nagy adatbázis-sémák esetén a SqlPackage-t futtató kliens gépen a memóriaigény jelentős lehet.

Alacsony kiszolgálói erőforrás-felhasználás

Az SqlPackage alapértelmezés szerint 8-ra állítja a kiszolgáló párhuzamosságát. Ha alacsony szervererőforrás-fogyasztást észlelsz, a paraméter értékének MaxParallelism növelése javíthatja a teljesítményt.

Hozzáférési jogkivonat

/AccessToken: Az or /at: paraméter használata lehetővé teszi a token alapú hitelesítést a SqlPackage számára, de a token átadása a parancsnak bonyolult lehet. Ha hozzáférési token objektumot parszírsz PowerShellben, vagy add át explicit módon a string értéket, vagy tekerd be a hivatkozást a token tulajdonságra .$() Például:

$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

Ha az SqlPackage nem tud csatlakozni, előfordulhat, hogy a kiszolgáló nem engedélyezi a titkosítást, vagy a konfigurált tanúsítvány nem megbízható hitelesítésszolgáltatótól (például önaláírt tanúsítványtól) lett kiállítva. Az SqlPackage parancsot módosíthatja úgy, hogy titkosítás nélkül csatlakozzon, vagy megbízzon a kiszolgálótanúsítványban. A ajánlott eljárás, a kiszolgálóval való megbízható titkosított kapcsolat létesítése.

  • Csatlakozás titkosítás nélkül: /SourceEncryptConnection:False vagy /TargetEncryptConnection:False
  • Megbízható kiszolgálótanúsítvány: /SourceTrustServerCertificate:True vagy /TargetTrustServerCertificate:True

Az alábbi figyelmeztető üzenetek egyikét vagy többet láthatod SQL instance-hoz való csatlakozáskor, amelyek arra utalnak, hogy a parancssori paraméterek módosítását igényelhetik a szerverhez való csatlakozáshoz:

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.

Az SqlPackage kapcsolatbiztonsági változásairól további információt Az SqlPackage 161kapcsolatbiztonsági fejlesztései című cikkben talál.

Importálási műveleti hiba 2714 korlátozás esetén

Amikor importálási műveletet hajtasz végre, ha egy objektum már létezik, akkor 2714-es hibát kaphatsz:

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

A következő okok és megoldások megkerülik ezt a hibát:

  1. Ellenőrizze, hogy az importálni kívánt cél egy üres adatbázis-e.
  2. Ha az adatbázisodban vannak olyan korlátok, amelyek az DEFAULT attribútumot használják (ahol az SQL Server véletlenszerű nevet rendel a korlátozáshoz), és egy kifejezetten nevelt korlátozást, akkor kétszer is létrehozhat ugyanazt a nevű korlátozást. Használd az összes explicit nevű korlátozást (ne használd DEFAULT), vagy használd az összes rendszer-definiált nevet (használd DEFAULT).
  3. Szerkeszd manuálisan a model.xml fájlt, és nevezd át a hibát okozó nevű megszorítást egyedi névre. Ezt a lehetőséget csak akkor lehet végrehajtani, ha a Microsoft ügyfélszolgálata utasítja, és fennáll a .bacpac megsérülésének kockázata.

Verem túlcsordulási hiba

A sok beágyazott utasítást tartalmazó nagy T-SQL-szkriptek időszakos vagy tartós veremtúlcsordulási kivételeket okozhatnak. Amikor ez a feltétel bekövetkezik, a hibaüzenet tartalmazza a(z) Stack overflow szöveget és egy veremkivonatot:

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)

Az SqlPackage paramétere minden parancson elérhető, /ThreadMaxStackSize:, amely megadja az SqlPackage folyamatot futtató szál maximális veremméretét. Az alapértelmezett értéket az SqlPackage-t futtató .NET-verzió határozza meg. Nagy érték beállítása befolyásolhatja a SqlPackage általános teljesítményét. Ennek az értéknek a növelése azonban megoldhatja az ágyazott utasítások okozta veremtúlcsordulási kivételt. Alakítsa át a T-SQL-kódot úgy, hogy ahol csak lehetséges, elkerülje a veremtúlcsordulási kivételeket. Ha nem tudsz refaktorozni, használd a /ThreadMaxStackSize: paramétert megoldásként.

Amikor használod a /ThreadMaxStackSize: paramétert, hangold az ismétlődő műveleteket a legalacsonyabb értékre, amely feloldja a stack túlcsordulás kivételét, ha teljesítménycsökkenést észlelsz. A paraméter értéke megabájtokban (MB) van. Például tesztelhetsz olyan értékeket, mint 10 és 100.

Az importálási műveletekre vonatkozó tippek

Nagy táblákat vagy sok indexet tartalmazó táblákat magában foglaló importálások esetén a /p:RebuildIndexesOfflineForDataPhase=True vagy a /p:DisableIndexesForDataPhase=False használata javíthatja a teljesítményt. Ezek a tulajdonságok úgy módosítják az index-újraépítési műveletet, hogy offline állapotban történjen, vagy ne történjen meg. Ezeket a tulajdonságokat és más tulajdonságokat használhatod a SqlPackage import művelet hangolásához.

Az indexek importálás után le vannak tiltva

Az adatok hatékony betöltéséhez az import letiltja a nem klaszterezett indexeket az adatfázis előtt, majd utána újraépíti őket (ez az alapértelmezett /p:DisableIndexesForDataPhase=True viselkedés). Ha az importot megszakítják vagy meghibásodik az adat betöltése után, de az újraépítés befejezése előtt, egy vagy több nem klaszterezett index letiltva maradhat. A letiltott index metaadatban marad, de a lekérdezésoptimalizáló figyelmen kívül hagyja azt, ami lassú lekérdezéseket okozhat egy egyébként sikeres importálás után.

A letiltott indexek megtalálásához nézze meg a sys.indexes katalógus nézetének oszlopátis_disabled:

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;

A letiltott index újbóli engedélyezéséhez építse újra azt a(z) ALTER INDEX paranccsal. Használja a ALTER INDEX ALL ... REBUILD elemet az összes letiltott index engedélyezéséhez egy táblában:

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

További információért lásd: Indexek és korlátozások engedélyezése.

Exportálási műveleti tippek

Ahhoz, hogy egy export tranzakcióban konzisztens legyen, győződjön meg róla, hogy az export során nem történik írási tevékenység, vagy hogy tranzakciósan konzisztens adatbázisból exportálsz. Ha az import során hibákat kapsz idegen kulcskorlátokkal kapcsolatban, az export nem lehet tranzakciós konzisztens az exportfolyamat során beillesztett vagy frissített rekordok miatt.

Teljesítmény exportálás közben

Az export során a teljesítményromlás gyakori oka a megoldatlan objektumhivatkozások. Ez a probléma arra készteti, hogy a SqlPackage többször is megpróbálja megoldani az objektumot. Például egy olyan nézet definiált, amely egy táblára hivatkozik, de a tábla már nem létezik az adatbázisban. Ha nem oldott hivatkozások jelennek meg az exportálási naplóban, érdemes lehet kijavítani az adatbázis sémáját az exportálási teljesítmény javítása érdekében.

Az exportálási folyamat során a rendszer tömöríti a táblaadatokat a bacpac-fájlban. A /p:CompressionOptionFastbeállítás , SuperFast, vagy NotCompressed javíthatja az exporti folyamat sebességét, miközben a kimeneti bacpac fájlt kevésbé tömöríti.

Az adatbázisséma és -adatok beszerzéséhez a sémaérvényesítés kihagyásával hajtsa végre az Exportálást a /p:VerifyExtraction=Falsetulajdonsággal. Érvénytelen exportálás hozható létre, amely nem importálható.

Lemezterület exportálás közben

Olyan helyzetekben, amikor az operációs rendszer lemezhelye korlátozott és kimerül az exportálás során, használd /p:TempDirectoryForTableData az adatok pufferezésére egy alternatív lemezre történő exporthoz. A művelethez szükséges terület nagy lehet, és az adatbázis teljes méretéhez viszonyítva van. A SqlPackage export műveletet úgy állíthatod be, hogy ezt és más tulajdonságokat állíts.

Azure SQL Database

Az alábbi tippek az Azure SQL Database-beli importálás vagy exportálás Azure-beli virtuális gépről történő futtatására vonatkoznak:

  • A legjobb teljesítmény érdekében használja az üzletileg kritikus vagy prémium szintű adatbázist.
  • SSD-tároló használata a virtuális gépen.
  • Győződjön meg arról, hogy van elég hely a bacpac kibontásához.
  • Hajtsa végre az SqlPackage parancsot az adatbázissal azonos régióban lévő virtuális gépről.
  • Gyorsított hálózatkezelés engedélyezése a virtuális gépen.

További információért a PowerShell szkript használatával az importművelet részleteinek gyűjtésére lásd: Lesson Learned #211: SQLPackage importi folyamat monitorozása.

További erőforrások

Az Azure Database támogatási blogja számos cikket tartalmaz az Azure SQL Database hibaelhárításáról és teljesítményhangolásáról, köztük az SqlPackage-ről szóló cikkeket.

A legrelevánsabb cikkek közé tartoznak a következők:

Kapcsolódó tartalom

  • Last updated on