Bagikan melalui

Memecahkan masalah dan performa dengan SqlPackage

  • Artikel

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. Saat membaca halaman dokumentasi tertentu untuk setiap tindakan untuk memahami parameter dan properti yang tersedia disarankan, artikel ini berfungsi sebagai titik awal dalam menyelidiki operasi SqlPackage.

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 dotnet SqlPackage, yang memungkinkan menjalankan perintah SqlPackage dari prompt perintah di direktori apa pun:

  1. Unduh zip untuk SqlPackage di .NET 8 untuk sistem operasi Anda (Windows, macOS, atau Linux).
  2. Unzip archive seperti yang diarahkan pada halaman unduhan.
  3. 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.

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

Masalah umum

Kesalahan Timeout

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. Default: 60
  • /p:DatabaseLockTimeout=: Menentukan batas waktu penguncian database dalam hitung 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.

  • Koneksi tanpa enkripsi: /SourceEncrypt Koneksi ion=False atau /TargetEncrypt Koneksi ion=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 ion 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:

  1. Verifikasi bahwa tujuan yang Anda impor adalah database kosong.
  2. 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 bernama secara eksplisit (tidak menggunakan DEFAULT), atau semua nama yang ditentukan sistem (menggunakan DEFAULT).
  3. 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 kerusakan .bacpac.

Pengecualian luapan tumpukan

Skrip T-SQL besar dengan banyak pernyataan berlapis sering menjadi penyebab pengecualian luapan tumpukan terputus-terputus 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 luapan tumpukan yang disebabkan oleh pernyataan berlapis. Pemfaktoran ulang kode T-SQL disarankan untuk menghindari pengecualian luapan tumpukan jika memungkinkan, tetapi /ThreadMaxStackSize: parameter dapat digunakan sebagai solusinya.

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

Diagnostik

Log sangat penting untuk pemecahan masalah. Ambil log diagnostik ke file dengan /DiagnosticsFile:<filename> parameter .

Lebih banyak data pelacakan terkait performa dapat dicatat dengan mengatur variabel DACFX_PERF_TRACE=true lingkungan sebelum menjalankan SqlPackage. Untuk mengatur variabel lingkungan ini di PowerShell, gunakan perintah berikut:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

Mengimpor tips tindakan

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 terjadi secara offline atau tidak terjadi. Properti tersebut dan properti lainnya tersedia untuk menyetel operasi Impor SqlPackage.

Mengekspor tips tindakan

Penyebab umum penurunan performa selama ekspor adalah referensi objek yang tidak terselesaikan, yang menyebabkan SqlPackage mencoba menyelesaikan objek beberapa kali. Misalnya, tampilan ditentukan yang mereferensikan tabel dan tabel tidak lagi ada dalam database. Jika referensi yang belum terselesaikan muncul di log ekspor, pertimbangkan untuk memperbaiki skema database untuk meningkatkan performa 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 menyetel operasi Ekspor SqlPackage.

Selama proses ekspor, data tabel dikompresi dalam file bacpac. Penggunaan /p:CompressionOption diatur ke Fast, SuperFast, atau NotCompressed dapat meningkatkan kecepatan proses ekspor saat mengompresi file bacpac output lebih sedikit.

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.

Database Azure SQL

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 zip bacpac.
  • 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:

Konten terkait