Memecahkan masalah dan performa dengan SqlPackage

Dalam beberapa skenario, operasi SqlPackage membutuhkan waktu lebih lama dari yang diharapkan atau gagal diselesaikan. Artikel ini menjelaskan beberapa taktik yang sering disarankan untuk memecahkan masalah atau meningkatkan performa operasi ini. Artikel ini berfungsi sebagai titik awal dalam menyelidiki operasi SqlPackage, meskipun disarankan untuk membaca halaman dokumentasi spesifik untuk setiap tindakan guna memahami parameter dan properti yang tersedia.

Strategi keseluruhan

Sebagai pedoman umum, performa yang lebih baik dapat diperoleh melalui versi .NET SqlPackage alih-alih versi .NET Framework yang diinstal melalui DacFramework.msi.

Jika Anda tidak dapat menginstal alat SqlPackage dotnet, yang memungkinkan menjalankan perintah SqlPackage dari prompt perintah di direktori mana pun:

Unduh zip untuk SqlPackage di .NET 8 untuk sistem operasi Anda (Windows, macOS, atau Linux).
Ekstrak arsip sesuai petunjuk pada halaman unduhan.
Buka perintah dan ubah direktori (cd) ke folder SqlPackage.

Penting untuk menggunakan versi terbaru SqlPackage yang tersedia karena peningkatan performa dan perbaikan bug dirilis secara teratur.

Ganti SqlPackage untuk Layanan Impor/Ekspor

Jika Anda mencoba menggunakan Layanan Impor/Ekspor untuk mengimpor atau mengekspor database, Anda dapat menggunakan SqlPackage untuk melakukan operasi yang sama dengan kontrol lebih besar pada parameter dan properti opsional. Postingan blog Mengoptimalkan Impor BACPAC - SqlPackage dengan Benar! menelusuri langkah-langkah untuk menggunakan SqlPackage alih-alih Layanan Impor/Ekspor dalam .bacpac impor.

Untuk Impor, contoh perintah adalah:

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

Untuk Ekspor, contoh perintah adalah:

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

Alternatif untuk nama pengguna dan kata sandi, autentikasi multifaktor dapat digunakan untuk mengautentikasi melalui autentikasi Microsoft Entra (sebelumnya Azure Active Directory) dengan autentikasi multifaktor. Ganti parameter nama pengguna dan kata sandi untuk /ua:true dan /tid:"yourdomain.onmicrosoft.com".

Diagnostics

Mendiagnosis kesalahan dan perilaku tak terduga di SqlPackage didukung oleh log diagnostik dan paket diagnostik. Log diagnostik sangat penting untuk pemecahan masalah dan diambil ke file dengan parameter /DiagnosticsFile:<filename>.

Tingkat detail dalam output diagnostik dikontrol melalui parameter /DiagnosticsLevel. Nilai Information dan Verbose berguna dalam mendapatkan detail selengkapnya.

Data pelacakan terkait performa dapat dicatat dengan mengatur variabel lingkungan DACFX_PERF_TRACE=true sebelum menjalankan SqlPackage. Data pelacakan meningkatkan output log, jadi hanya termasuk saat mendiagnosis tantangan performa. Untuk mengatur variabel lingkungan ini di PowerShell, gunakan perintah berikut:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Di SqlPackage 162,5 dan yang lebih baru, paket diagnostik dapat dihasilkan untuk membantu pemecahan masalah. Paket diagnostik berisi versi SqlPackage, perintah yang dijalankan, informasi tentang model database sumber dan target, dan output perintah. Untuk menghasilkan paket diagnostik, gunakan parameter /DiagnosticsPackageFile:<filename>.

Masalah umum

Kesalahan batas waktu

Untuk masalah yang terkait dengan batas waktu, properti berikut dapat digunakan untuk menyetel koneksi antara SqlPackage dan instans SQL:

/p:CommandTimeout=: Menentukan batas waktu perintah dalam detik saat kueri dijalankan. Bawaan: 60
/p:DatabaseLockTimeout=: Menentukan batas waktu penguncian database dalam detik. -1 dapat digunakan untuk menunggu tanpa batas waktu, default: 60
/p:LongRunningCommandTimeout=: Menentukan batas waktu perintah yang berjalan lama dalam detik. Nilai default, 0, digunakan untuk menunggu tanpa batas waktu.

Konsumsi sumber daya klien

Untuk perintah ekspor dan ekstrak, data tabel diteruskan ke direktori sementara ke buffer sebelum ditulis ke file bacpac/dacpac. Persyaratan penyimpanan ini bisa besar dan relatif terhadap ukuran penuh data yang akan diekspor. Tentukan direktori sementara alternatif dengan properti /p:TempDirectoryForTableData=<path>.

Model skema dikompilasi dalam memori, sehingga untuk skema database besar, persyaratan memori pada komputer klien yang menjalankan SqlPackage bisa signifikan.

Konsumsi sumber daya server rendah

Secara default, SqlPackage mengatur paralelisme server maksimum ke 8. Jika Anda mencatat konsumsi sumber daya server yang rendah, meningkatkan nilai MaxParallelism parameter dapat meningkatkan performa.

Token akses

/AccessToken: Menggunakan parameter atau /at: memungkinkan autentikasi berbasis token untuk SqlPackage, namun meneruskan token ke perintah bisa rumit. Jika Anda mengurai objek token akses di PowerShell, berikan nilai string secara eksplisit atau bungkus referensi ke properti token dalam $(). Contohnya:

$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

Jika SqlPackage gagal tersambung, server mungkin tidak mengaktifkan enkripsi atau sertifikat yang dikonfigurasi mungkin tidak dikeluarkan dari otoritas sertifikat tepercaya (seperti sertifikat yang ditandatangani sendiri). Anda dapat mengubah perintah SqlPackage agar tersambung tanpa enkripsi atau mempercayai sertifikat server. Praktik terbaik adalah memastikan bahwa koneksi terenkripsi tepercaya ke server dapat dibuat.

Sambungkan tanpa enkripsi: /SourceEncryptConnection:False atau /TargetEncryptConnection:False
Sertifikat server kepercayaan: /SourceTrustServerCertificate:True atau /TargetTrustServerCertificate:True

Anda dapat melihat salah satu pesan peringatan berikut saat menyambungkan ke instans SQL, yang menunjukkan bahwa parameter baris perintah dapat memerlukan perubahan untuk menyambungkan ke 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.

Informasi selengkapnya tentang perubahan keamanan koneksi di SqlPackage tersedia dalam Peningkatan Keamanan Koneksi di SqlPackage 161.

Kesalahan tindakan impor 2714 untuk batasan

Saat melakukan tindakan impor, Anda mungkin menerima kesalahan 2714 jika objek sudah ada:

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

Berikut adalah penyebab dan solusi untuk mengatasi kesalahan ini:

Pastikan bahwa tujuan database yang Anda impor adalah kosong.
Jika database Anda memiliki batasan yang menggunakan atribut DEFAULT (di mana SQL Server menetapkan nama acak ke batasan) dan batasan bernama secara eksplisit, batasan dengan nama yang sama mungkin dibuat dua kali. Anda harus menggunakan semua batasan yang disebutkan secara eksplisit (tidak menggunakan DEFAULT), atau semua nama yang ditentukan sistem (menggunakan DEFAULT).
Edit model.xml secara manual dan ganti nama batasan dengan nama yang mengalami kesalahan ke nama unik. Opsi ini harus dilakukan hanya jika diarahkan oleh dukungan Microsoft dan menimbulkan risiko .bacpac kerusakan.

Pengecualian stack overflow

Skrip T-SQL yang besar dengan banyak pernyataan bersarang sering menjadi penyebab terjadinya exception Stack Overflow yang bersifat sementara atau persisten. Jika demikian, pesan kesalahan akan menyertakan teks Stack overflow dan jejak tumpukan:

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)

Parameter untuk SqlPackage tersedia di semua perintah, /ThreadMaxStackSize:, yang menentukan ukuran tumpukan maksimum untuk utas yang menjalankan proses SqlPackage. Nilai default ditentukan oleh versi .NET yang menjalankan SqlPackage. Menetapkan nilai besar dapat memengaruhi performa SqlPackage secara keseluruhan, namun meningkatkan nilai ini dapat mengatasi pengecualian kelebihan tumpukan yang disebabkan oleh pernyataan berlapis. Memfaktorkan ulang kode T-SQL disarankan untuk menghindari kesalahan stack overflow jika memungkinkan, tetapi parameter /ThreadMaxStackSize: dapat digunakan sebagai solusi alternatif.

Saat menggunakan parameter /ThreadMaxStackSize:, disarankan untuk mengatur operasi berulang ke nilai terendah yang menyelesaikan kesalahan kelebihan tumpukan jika terdapat dampak performa. Nilai parameter dalam megabyte (MB), nilai contoh untuk pengujian sebagai solusinya termasuk 10 dan 100.

Saran tindakan impor

Untuk impor yang berisi tabel atau tabel besar dengan banyak indeks, penggunaan /p:RebuildIndexesOfflineForDataPhase=True atau /p:DisableIndexesForDataPhase=False dapat meningkatkan performa. Properti ini mengubah operasi pembangunan ulang indeks agar dilakukan secara offline atau tidak dilakukan. Properti tersebut dan properti lainnya tersedia untuk menyetel operasi SqlPackage Import.

Tips tindakan ekspor

Agar ekspor konsisten secara transaksional, Anda harus memastikan bahwa tidak ada aktivitas tulis yang terjadi selama ekspor, atau bahwa Anda mengekspor dari salinan database Anda yang konsisten secara transaksional . Menerima kesalahan tentang batasan kunci asing selama impor dapat menunjukkan bahwa ekspor tidak konsisten secara transaksional karena rekaman yang dimasukkan atau diperbarui selama proses ekspor.

Performa selama ekspor

Penyebab umum penurunan performa selama ekspor adalah referensi objek yang tidak terselesaikan, yang menyebabkan SqlPackage mencoba menyelesaikan objek beberapa kali. Misalnya, ditentukan sebuah tampilan yang mereferensikan tabel yang sudah tidak ada lagi dalam database. Jika referensi yang belum terselesaikan muncul di log ekspor, pertimbangkan untuk memperbaiki skema database untuk meningkatkan performa ekspor.

Selama proses ekspor, data tabel dikompresi dalam file bacpac. Penggunaan /p:CompressionOption yang diatur ke Fast, SuperFast, atau NotCompressed mungkin meningkatkan kecepatan proses ekspor sambil mengurangi tingkat kompresi file bacpac output.

Untuk mendapatkan skema database dan data saat melewati validasi skema, lakukan Ekspor dengan properti /p:VerifyExtraction=False. Ekspor yang tidak valid mungkin dihasilkan yang tidak dapat diimpor.

Ruang disk selama ekspor

Dalam skenario di mana ruang disk OS terbatas dan kehabisan selama ekspor, penggunaan /p:TempDirectoryForTableData memungkinkan data untuk ekspor di-buffer pada disk alternatif. Ruang yang diperlukan untuk tindakan ini mungkin besar dan relatif terhadap ukuran penuh database. Itu dan properti lain tersedia untuk mengatur operasi SqlPackage Export.

Azure SQL Database

Tips berikut khusus untuk menjalankan impor atau ekspor terhadap Azure SQL Database dari komputer virtual Azure (VM):

Gunakan database tingkat Business Critical atau Premium untuk performa terbaik.
Gunakan penyimpanan SSD pada VM.
Pastikan ada cukup ruang untuk membuka resleting tas punggung.
Jalankan SqlPackage dari VM di wilayah yang sama dengan database.
Aktifkan jaringan terakselerasi di VM.

Untuk informasi selengkapnya tentang menggunakan skrip PowerShell untuk mengumpulkan informasi selengkapnya tentang operasi impor, lihat Pelajaran Yang Dipelajari #211: Memantau Proses Impor SQLPackage.

Sumber daya lainnya

Blog Dukungan Azure Database berisi banyak artikel tentang pemecahan masalah dan penyetelan performa untuk Azure SQL Database, termasuk beberapa artikel di SqlPackage.

Beberapa artikel yang paling relevan meliputi:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-03-05