Aracılığıyla paylaş

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.

SqlPackage dotnet aracını, yani SqlPackage komutlarını herhangi bir dizindeki komut isteminden çalıştırmanızı sağlayan aracı yükleyemiyorsanız:

  1. İşletim sisteminiz (Windows, macOS veya Linux) için .NET 8'de SqlPackage zip'ini indirin.
  2. İndirme sayfasındaki talimatlara göre 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ığından SqlPackage'ın kullanılabilir en son sürümünü kullanmak önemlidir.

İç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.

İç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>

Kullanıcı adı ve parolaya alternatif olarak çok faktörlü kimlik doğrulaması, çok faktörlü kimlik doğrulamasıyla Microsoft Entra kimlik doğrulaması (eski adı Azure Active Directory) aracılığıyla kimlik doğrulaması yapmak için kullanılabilir. /ua:true ve /tid:"yourdomain.onmicrosoft.com"için kullanıcı adı ve parola parametrelerini değiştirin.

Tanılama

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.

Tanılama çıkışındaki ayrıntı düzeyi, /DiagnosticsLevel parametresi aracılığıyla denetlenmektedir. Information ve Verbose değerleri daha fazla ayrıntı elde etmek için yararlıdır.

SqlPackage çalıştırılmadan önce ortam değişkeni DACFX_PERF_TRACE=true ayarlanarak performansla ilgili izleme verileri kaydedilebilir. İzleme verileri günlük çıktıyı artırır, bu nedenle yalnızca performans zorluklarını teşhis ederken dahil edin. 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 sonraki sürümlerinde, sorun gidermeye yardımcı olacak bir tanılama paketi oluşturulabilir. 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şımlarıyla ilgili sorunlar için, SqlPackage ile SQL örneği arasındaki bağlantıyı ayarlamak için aşağıdaki özellikler kullanılabilir:

  • /p:CommandTimeout=: Sorgu yürütülürken komut zaman aşımını saniyeler içinde belirtir. Varsayılan: 60
  • /p:DatabaseLockTimeout=: Veritabanı kilit zaman aşımını saniye olarak belirtir. -1 süresiz olarak beklemek için kullanılabilir, varsayılan: 60
  • /p:LongRunningCommandTimeout=: Uzun süre çalışan komut zaman aşımını saniye olarak belirtir. Varsayılan değer olan 0, süresiz olarak beklemek için kullanılır.

İstemci kaynak tüketimi

Dışarı aktarma ve ayıklama komutları için tablo verileri, bacpac/dacpac dosyasına yazılmadan önce ara belleklendirilen geçici bir dizine geçirilir. Bu depolama gereksinimi büyük olabilir ve dışarı aktarılacak verilerin tam boyutuna göre değişir. /p:TempDirectoryForTableData=<path>özelliğine sahip alternatif bir geçici dizin belirtin.

Şema modeli bellekte derlendiğinden, büyük veritabanı şemaları için SqlPackage çalıştıran istemci makinesinde 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üketimine dikkat ederseniz, MaxParallelism parametresinin değerini artırmak performansı artırabilir.

Erişim belirteci

/AccessToken: veya /at: parametresini kullanmak SqlPackage için belirteç tabanlı kimlik doğrulamasını etkinleştirir, ancak belirteci komuta geçirmek karmaşık olabilir. PowerShell'de bir erişim belirteci nesnesini işliyorsanız, dize değerini açıkça geçirin veya belirteç özelliğine başvuruyu $() ile sarın. Mesela:

$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)

Bağlantı

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 aşağıdaki uyarı iletilerinden herhangi birini görebilirsiniz; bu, komut satırı parametrelerinin sunucuya bağlanmak için değişiklik gerektirebileceğini belirtir:

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

İçeri aktarma eylemi gerçekleştirirken, bir nesne zaten varsa 2714 hatasını 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 DEFAULT özniteliğini (SQL Server'ın kısıtlamaya rastgele bir ad atadığı) ve açıkça adlandırılmış bir kısıtlama kullanan kısıtlamalar varsa, aynı ada sahip bir kısıtlama iki kez oluşturulabilir. Açıkça adlandırılmış kısıtlamaların tümünü (DEFAULT'u kullanmadan) veya sistem tarafından tanımlanan adların tümünü (DEFAULT'u kullanarak) kullanmanız gerekir.
  3. model.xml dosyasını el ile düzenleyin ve hata yaşanan kısıtlamayı benzersiz bir adla değiştirin. 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 geçmiş deyim içeren büyük T-SQL betikleri, genellikle aralıklı veya kalıcı yığın taşması istisnalarına neden olur. Böyle bir durumda hata iletisi, Stack overflow metnini ve yığın izlemesini 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 ayarlamak SqlPackage'ın genel performansını etkileyebilir, ancak bu değerin artırılması iç içe geçmiş deyimlerin neden olduğu yığın taşması özel durumunu çözebilir. Mümkün olduğunda yığın taşması özel durumlarını önlemek için T-SQL kodunun yeniden düzenlenmesi önerilir, ancak geçici çözüm olarak /ThreadMaxStackSize: parametresi kullanılabilir.

/ThreadMaxStackSize: parametresini kullanırken, performans etkisine dikkat edilirse yinelenen işlemleri yığın taşması özel durumunu çözen en düşük değere ayarlamanız önerilir. parametresinin değeri megabayt (MB) cinsindendir; geçici çözüm olarak test için örnek değerler 10 ve 100'dür.

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

Büyük tablolar veya çok sayıda dizine sahip tablolar içeren içeri aktarmalar için, /p:RebuildIndexesOfflineForDataPhase=True veya /p:DisableIndexesForDataPhase=False kullanımı 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 ve diğer özellikler, SqlPackage İçe Aktarma işlemini ayarlamak için kullanılabilir.

Dışarı aktarma eylemi ipuçları

Dışarı aktarma sırasında performans düşüşünün yaygın bir nedeni çözümlenmemiş nesne başvurularıdır ve bu da SqlPackage'ın nesneyi birden çok kez çözümlemeye çalışmasına neden olur. Örneğin, bir tabloya başvuran bir görünüm tanımlanır ve tablo artık veritabanında yoktur. 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.

İşletim sistemi disk alanının sınırlı olduğu ve dışarı aktarma sırasında tükendiği senaryolarda, /p:TempDirectoryForTableData kullanımı dışarı aktarma verilerinin alternatif bir diskte arabelleğe alınmasına olanak tanır. Bu eylem için gereken alan büyük olabilir ve veritabanının tam boyutuna göre değişir. Bu ve diğer özellikler, SqlPackage dışa aktarma işlemini ayarlamak için kullanılabilir.

Dışarı aktarma işlemi sırasında tablo verileri bacpac dosyasında sıkıştırılır. /p:CompressionOption, Fastveya SuperFast olarak ayarlanmış NotCompressed kullanımı, çıkış bacpac dosyasını daha az sıkıştırırken dışarı aktarma işlemi 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.

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.

İçeri aktarma işlemi hakkında daha fazla bilgi toplamak için PowerShell betiğini kullanma hakkında daha fazla bilgi için bkz. Öğrenilen Ders #211: SQLPackage İçeri Aktarma İşlemini İzleme.

Diğer kaynaklar

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