SqlPackage ile ilgili sorunları ve performansı giderme

Bazı senaryolarda SqlPackage işlemleri beklenenden uzun sürer veya tamamlanamadı. Bu makalede, bu işlemlerin performansını gidermek veya iyileştirmek için sık önerilen bazı taktikler açıklanmaktadır. Kullanılabilir parametreleri ve özellikleri anlamak için her eylemin belirli belge sayfasını okumak önerilir ancak bu makale SqlPackage işlemlerini araştırmada bir başlangıç noktası görevi görür.

Genel strateji

Genel yönergeler olarak, DacFramework.msiaracılığıyla yüklenen .NET Framework sürümü yerine SqlPackage'ın .NET sürümü ile daha iyi performans elde edilebilir.

Eğer herhangi bir dizindeki komut sabitinden SqlPackage komutlarını çalıştırmanızı sağlayan SqlPackage dotnet aracını yükleyemiyorsan:

  1. İşletim sisteminiz (Windows, macOS veya Linux) için .NET 8'de SqlPackage zip'ini indirin.
  2. İndirme sayfasında belirtildiği şekilde arşivi açın.
  3. Bir komut istemi açın ve dizini (cd) SqlPackage klasörüne değiştirin.

Performans iyileştirmeleri ve hata düzeltmeleri düzenli olarak yayınlandığı için SqlPackage'in en son mevcut sürümünü kullanın.

İçeri/Dışarı Aktarma Hizmeti için SqlPackage'ın yerini alma

Veritabanınızı içeri veya dışarı aktarmak için İçeri/Dışarı Aktarma Hizmeti'ni kullanmayı denediyseniz, isteğe bağlı parametreler ve özellikler üzerinde daha fazla denetimle aynı işlemi gerçekleştirmek için SqlPackage'ı kullanabilirsiniz. BACPAC İçe Aktarımlarını Optimizasyon - SqlPackage'ı Doğru Kullanma! blog gönderisi, .bacpac içe aktarmada İçeri/Dışarı Aktarma Hizmeti yerine SqlPackage'ı kullanma adımlarında rehberlik eder.

İçeri Aktarma için örnek bir komut:

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

Dışarı Aktarma için örnek bir komut:

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

Microsoft Entra kimlik doğrulaması ile kimlik doğrulama yapmak için kullanıcı adı ve şifreye alternatif olarak çok faktörlü kimlik kullan. /ua:true ve /tid:"contoso.onmicrosoft.com"için kullanıcı adı ve parola parametrelerini değiştirin.

Diagnostics

SqlPackage'da hataları ve beklenmeyen davranışları tanılama, tanılama günlükleri ve bir tanılama paketi tarafından desteklenir. Tanılama günlükleri sorun giderme için gereklidir ve /DiagnosticsFile:<filename> parametresiyle bir dosyaya kaydedilir.

Parametre aracılığıyla tanı çıktısındaki /DiagnosticsLevel detay seviyesini kontrol edin. Daha fazla ayrıntı almak için Verbose ve Information değerlerini kullanın.

SqlPackage çalıştırmadan önce ortam değişkenini DACFX_PERF_TRACE=true ayarlayarak performansla ilgili iz verilerini kaydedin. İz verisi, log çıktısını artırır, bu yüzden sadece performans zorluklarını teşhis ederken dahil edilir. PowerShell'de bu ortam değişkenini ayarlamak için aşağıdaki komutu kullanın:

Set-Item -Path Env:DACFX_PERF_TRACE -Value true

SqlPackage 162.5 ve sonrasında ise sorun gidermeye yardımcı olacak bir tanı paketi oluşturabilirsiniz. Tanılama paketi SqlPackage sürümünü, yürütülen komutu, kaynak ve hedef veritabanı modelleri hakkındaki bilgileri ve komutun çıkışını içerir. Tanılama paketi oluşturmak için /DiagnosticsPackageFile:<filename> parametresini kullanın.

Yaygın sorunlar

Zaman aşımı hataları

Zaman aşımına bağlı sorunlar için, SqlPackage ile SQL örneği arasındaki bağlantıyı ayarlamak için aşağıdaki özellikleri kullanın:

  • /p:CommandTimeout=: Bir sorgu çalıştırıldığında komut zaman aşımını saniyeler cinsinden belirtir. Varsayılan: 60
  • /p:DatabaseLockTimeout=: Veritabanı kilit zaman aşımını saniye olarak belirtir. Süresiz beklemek için kullanın -1 . Varsayılan: 60
  • /p:LongRunningCommandTimeout=: Uzun süre çalışan komut zaman aşımını saniye olarak belirtir. Varsayılan değer, 0, sonsuza kadar bekler.

İstemci kaynak tüketimi

Dışa aktarma ve ayıklama komutlarında SqlPackage, tablo verilerini BACPAC veya DACPAC dosyasına yazmadan önce arabelleğe almak için geçici bir dizine aktarır. Bu depolama gereksinimi büyük olabilir ve dışa aktarılacak verinin tam boyutuna göre değişir. /p:TempDirectoryForTableData=<path>özelliğine sahip alternatif bir geçici dizin belirtin.

SqlPackage, şema modelini bellekte derler. Büyük veritabanı şemaları için, SqlPackage çalıştıran istemci makinede bellek gereksinimi önemli olabilir.

Düşük sunucu kaynak tüketimi

Varsayılan olarak, SqlPackage en yüksek sunucu paralelliğini 8 olarak ayarlar. Düşük sunucu kaynak tüketimi fark ederseniz, parametrenin MaxParallelism değerini artırmak performansı artırabilir.

Erişim belirteci

/at: veya /AccessToken: parametresinin kullanılması, SqlPackage için belirteç tabanlı kimlik doğrulamaya olanak tanır, ancak belirteci komuta geçirmek zor olabilir. PowerShell'de bir erişim belirteci nesnesini ayrıştırıyorsanız, dize değerini ya açıkça geçirin ya da belirteç özelliğine olan başvuruyu $() içine alın. Örneğin:

$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

SqlPackage bağlanamıyorsa, sunucuda şifreleme etkinleştirilmemiş olabilir veya yapılandırılan sertifika güvenilir bir sertifika yetkilisinden (otomatik olarak imzalanan sertifika gibi) verilmemiş olabilir. SqlPackage komutunu şifreleme olmadan bağlanacak veya sunucu sertifikasına güvenecek şekilde değiştirebilirsiniz. en iyi yöntem, sunucuya güvenilir bir şifreli bağlantı kuruladığından emin olmaktır.

  • Şifreleme olmadan bağlanma: /SourceEncryptConnection:False veya /TargetEncryptConnection:False
  • Sunucu sertifikasına güven: /SourceTrustServerCertificate:True veya /TargetTrustServerCertificate:True

Bir SQL örneğine bağlanırken, komut satırı parametrelerinin sunucuya bağlanmak için değişiklik gerektirebileceğini belirten aşağıdaki uyarı mesajlarından birini veya birkaçını görebilirsiniz:

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.

SqlPackage'daki bağlantı güvenliği değişiklikleri hakkında daha fazla bilgi için bkz. sqlpackage 161 Bağlantı Güvenliği Geliştirmeleri.

Kısıtlama için aktarma işlemi hatası 2714

Bir içe aktarma işlemi gerçekleştirdiğinizde, bir nesne zaten varsa 2714 hata kodunu alabilirsiniz:

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

Bu hatayı geçici olarak düzeltmenin nedenleri ve çözümleri şunlardır:

  1. İçeri aktardığınız hedefin boş bir veritabanı olduğunu doğrulayın.
  2. Veritabanınızda özniteliği DEFAULT (SQL Server kısıtlamaya rastgele bir isim atar) ve açıkça adlandırılmış bir kısıtlama varsa, aynı isimli bir kısıtlama iki kez oluşturulabilir. Tüm açıkça adlandırılmış kısıtlamaları kullanın (kullanmayın DEFAULT), veya tüm sistem tanımlı isimleri kullanın (kullanın DEFAULT).
  3. Dosyayı model.xml manuel olarak düzenleyin ve hataya neden olan isimle kısıtlamayı benzersiz bir isim olarak yeniden adlandırın. Bu seçenek yalnızca Microsoft desteği tarafından yönlendirildiğinde ve .bacpac bozulma riski oluşturduğunda uygulanmalıdır.

Yığın taşması hatası

Birçok iç içe girmiş ifade içeren büyük T-SQL betikleri, aralıklı veya kalıcı yığın taşma istisnalarına neden olabilir. Bu koşul oluştuğunda, hata mesajı metni Stack overflow ve bir yığın izini içerir:

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)

SqlPackage için bir parametre, sqlpackage işlemini çalıştıran iş parçacığı için en büyük yığın boyutunu belirten /ThreadMaxStackSize:tüm komutlarda kullanılabilir. Varsayılan değer, SqlPackage çalıştıran .NET sürümü tarafından belirlenir. Büyük bir değer belirlemek, SqlPackage'ın genel performansını etkileyebilir. Ancak, bu değerin artırılması, iç içe geçen ifadelerin neden olduğu yığın taşması istisnasını giderebilir. T-SQL kodunu mümkün olduğunca yığın taşma istisnalarından kaçınmak için yeniden yapılandırın. Eğer yeniden düzenleme yapamazsanız, parametreyi /ThreadMaxStackSize: bir çözüm olarak kullanın.

/ThreadMaxStackSize: parametresini kullandığınızda, performans üzerinde bir etki fark ederseniz, tekrarlanan işlemleri yığın taşması özel durumunu gideren en düşük değere ayarlayın. Parametrenin değeri megabayt cinsinden (MB) olarak belirlenir. Örneğin, ve 10100gibi değerleri test edebilirsiniz.

İçeri aktarma işlemi için ipuçları

Büyük tablolar veya çok sayıda dizine sahip tablolar içeren içe aktarma işlemlerinde, /p:RebuildIndexesOfflineForDataPhase=True ya da /p:DisableIndexesForDataPhase=False kullanmak performansı artırabilir. Bu özellikler sırasıyla dizin yeniden oluşturma işlemini çevrimdışı olacak veya gerçekleşmeyecek şekilde değiştirir. Bu özellikleri ve diğer özellikleri kullanarak SqlPackage İthalat işlemini ayarlayabilirsiniz.

Dizinler bir içe aktarmadan sonra devre dışı bırakılır

Veriyi verimli bir şekilde yüklemek için, bir içe aktarma işlemi veri aşamasından önce kümelenmiş olmayan indeksleri devre dışı bırakır ve sonrasında yeniden oluşturur (varsayılan /p:DisableIndexesForDataPhase=True davranış). Veri yüklendikten sonra ancak yeniden oluşturma tamamlanmadan önce aktarma kesilirse veya başarısız olursa, bir veya daha fazla kümelenmiş olmayan indeks devre dışı kalabilir. Devre dışı bırakılmış bir indeks meta veride kalır, ancak sorgu optimizörü bunu görmezden gelir; bu da başarılı görünen bir içe aktarmadan sonra yavaş sorgulara neden olabilir.

Devre dışı bırakılmış indeksleri bulmak için sys.indexes katalog görünümündeki sütuna bakınis_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;

Devre dışı bırakılmış bir dizini yeniden etkinleştirmek için ALTER INDEX ile yeniden oluşturun. Bir tabloda tüm devre dışı bırakılmış indeksleri etkinleştirmek için kullanılır ALTER INDEX ALL ... REBUILD :

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

Daha fazla bilgi için bkz. İndeksleri ve kısıtlamaları etkinleştir.

Dışarı aktarma eylemi ipuçları

Bir ihracatın işlem açısından tutarlı olması için, ya dışa aktarma sırasında yazma faaliyeti olmadığından ya da veritabanınızın işlem açısından tutarlı bir kopyasından dışa aktardığınızdan emin olun. İthalat sırasında yabancı anahtar kısıtlamalarıyla ilgili hata alırsanız, ihracat işlemi işlemi sırasında eklenen veya güncellenen kayıtlar nedeniyle işlemsel olarak tutarlı olmayabilir.

Dışarı aktarma sırasında performans

Dışa aktarma sırasında performans düşüşünün yaygın bir nedeni, çözülmemiş nesne referanslarıdır. Bu sorun, SqlPackage'nin nesneyi birden fazla kez çözmeye çalışmasına neden olur. Örneğin, bir tabloya referans veren ancak tablo artık veritabanında bulunmayan bir görünüm tanımlanır. Dışarı aktarma günlüğünde çözümlenmemiş başvurular görünüyorsa, dışarı aktarma performansını geliştirmek için veritabanının şemasını düzeltmeyi göz önünde bulundurun.

Dışarı aktarma işlemi sırasında tablo verileri bacpac dosyasında sıkıştırılır. SuperFast öğesini NotCompressed, /p:CompressionOption veya Fast olarak ayarlamak, çıktı bacpac dosyasını daha az sıkıştırarak dışa aktarma işleminin hızını artırabilir.

Şema doğrulamasını atlarken veritabanı şemasını ve verilerini almak için Export özelliğini gerçekleştirin. İçe aktarılamayan geçersiz bir dışa aktarma oluşturulabilir.

Dışarı aktarma sırasında disk alanı

İşletim sistemi disk alanının sınırlı olduğu ve dışa aktarma sırasında tükendiği durumlarda, verileri alternatif bir diskte dışa aktarmak için tampon yapmak için kullanın /p:TempDirectoryForTableData . Bu eylem için gereken alan büyük olabilir ve veritabanının tam boyutuna göre değişir. SqlPackage Export işlemini bu ve diğer özellikleri ayarlayarak ayarlayabilirsiniz.

Azure SQL Veritabanı

Aşağıdaki ipuçları, Bir Azure sanal makinesinden (VM) Azure SQL Veritabanı'na yönelik içeri veya dışarı aktarma çalıştırmaya özeldir:

  • En iyi performans için İş Açısından Kritik veya Premium katman veritabanını kullanın.
  • VM'de SSD depolama kullanın.
  • Bacpac'in fermuarını açmak için yeterli alan olduğundan emin olun.
  • SqlPackage'i veritabanıyla aynı bölgedeki bir VM'den yürütür.
  • VM'de hızlandırılmış ağı etkinleştirin.

Bir aktarma işlemi hakkında bilgi toplamak için PowerShell betikiyle ilgili daha fazla bilgi için Derson Learned #211: Monitoring SQLPackage Import Process'e bakınız.

Daha fazla kaynak

Azure Veritabanı Destek Blogu, SqlPackage ile ilgili çeşitli makaleler de dahil olmak üzere Azure SQL Veritabanı için sorun giderme ve performans ayarlama hakkında birçok makale içerir.

En ilgili makalelerden bazıları şunlardır:

İlgili içerik

  • Last updated on