Aracılığıyla paylaş

SqlPackage

SqlPackage , genel Data-Tier Application Framework (DacFx) API'lerinden bazılarını kullanıma sunarak veritabanı geliştirme görevlerini otomatik hale getiren bir komut satırı yardımcı programıdır. SqlPackage için birincil kullanım örnekleri SQL Server, Azure SQL ve Azure Synapse Analytics veritabanı ailesi için veritabanı taşınabilirliğine ve dağıtımlarına odaklanır. SqlPackage , Azure Pipelines ve GitHub eylemleri veya diğer CI/CD araçları kullanılarak otomatikleştirilebilir.

En son sürümü indirin. En son sürümle ilgili ayrıntılar için sürüm notlarına bakın.

Uyarı

Microsoft Entra ID, Azure Active Directory (Azure AD) içinyeni ad olsa da, mevcut ortamların kesintiye uğramasını önlemek için Azure AD yine de kullanıcı arabirimi alanları, bağlantı sağlayıcıları, hata kodları ve cmdlet'ler gibi sabit kodlanmış bazı öğelerde kalır. Bu makalede, iki ad birbirinin yerine kullanılabilir.

Taşınabilir -lik

Veritabanı taşınabilirliği, veritabanı şemasını ve verilerini SQL Server, Azure SQL ve Azure Synapse Analytics'in farklı örnekleri arasında taşıma özelliğidir. Veritabanını Azure SQL Veritabanı'ndan şirket içi SQL Server örneğine veya SQL Server'dan Azure SQL Veritabanı'na aktarma, veritabanı taşınabilirliğine örnek olarak verilebilir. SqlPackage, BACPAC dosyalarını oluşturan ve kullanan Dışarı ve İçeri Aktarma eylemleri aracılığıyla veritabanı taşınabilirliğini destekler. SqlPackage, verileri doğrudan içerebilen veya Azure Blob Depolama'da depolanan verilere başvuruda bulunabilen DACPAC dosyalarını oluşturup kullanan Ayıklama ve Yayımlama eylemleri aracılığıyla veritabanı taşınabilirliğini de destekler.

  • dışarı aktarma: Veritabanı şeması ve kullanıcı verileri dahil olmak üzere bağlı bir SQL veritabanını BACPAC dosyasına (.bacpac) aktarır.

  • İçeri aktarma: Şema ve tablo verilerini bir BACPAC dosyasından yeni bir kullanıcı veritabanına aktarır.

Dağıtımlar

Veritabanı dağıtımları, tabloya sütun ekleme veya saklı yordamın içeriğini değiştirme gibi bir veritabanı şemasını istenen durumla eşleşecek şekilde güncelleştirme işlemidir. SqlPackage , Yayımla ve Ayıkla eylemleri aracılığıyla veritabanı dağıtımlarını destekler. Yayımla eylemi bir veritabanı şemasını kaynak .dacpac dosyasının içeriğiyle eşleşecek şekilde güncelleştirirken, Ayıkla eylemi ise bağlı bir SQL veritabanından şemayı veya şemayı ve kullanıcı verilerini içeren bir veri katmanı uygulaması (.dacpac) dosyası oluşturur. SqlPackage, otomatik olarak hedef veritabanına gerekli değişiklikleri uygulayan bir dağıtım planı oluşturarak aynı yapıttan (.dacpac) hem yeni hem de mevcut veritabanlarına dağıtımlar sağlar. Dağıtım planı, değişiklikleri hedef veritabanına uygulamadan önce Betik veya DeployReport eylemleriyle gözden geçirilebilir.

  • Çıkarma: Bağlı bir SQL veritabanından şema veya şema ve kullanıcı verilerini içeren bir veri katmanı uygulaması (.dacpac) dosyası oluşturur.

  • Publish: Veritabanı şemasını bir kaynak .dacpac dosyasının şemasıyla eşleşecek şekilde artımlı olarak güncelleştirir. Veritabanı sunucuda yoksa yayımlama işlemi bunu oluşturur. Aksi takdirde, mevcut bir veritabanı güncelleştirilir.

  • DeployReport: Yayımlama eyleminin gerçekleştireceği değişiklikleri temsil eden bir XML raporu oluşturur.

  • DriftReport: Son kaydedildiğinden bu yana kayıtlı bir veritabanına uygulanan değişiklikleri temsil eden bir XML raporu oluşturur.

  • Betik: Hedefin şemasını kaynağın şemasıyla uyumlu hale getiren bir Transact-SQL artımlı güncelleme betiği oluşturur.

Komut Satırı Söz Dizimi

SqlPackage , komut satırında belirtilen parametreleri, özellikleri ve SQLCMD değişkenlerini kullanarak belirtilen eylemleri başlatır.

SqlPackage {parameters} {properties} {SQLCMD variables}

SqlPackage komut satırı söz dizimi hakkında daha fazla bilgi , SqlPackage CLI başvurusu ve tek tek eylem sayfalarında ayrıntılı olarak yer alır.

Yardımcı program komutları

Sürüm

sqlpackage sürümünü yapı numarası olarak gösterir. etkileşimli istemlerde ve otomatik işlem hatlarında kullanılabilir.

SqlPackage /Version

Yardım

/? veya /help:Truekullanarak SqlPackage kullanım bilgilerini görüntüleyebilirsiniz.

SqlPackage /?

Belirli bir eyleme özgü parametre ve özellik bilgileri için, bu eylemin parametresine ek olarak yardım parametresini kullanın.

SqlPackage /Action:Publish /?

Kimlik doğrulama

SqlPackage, SqlClient'da kullanılabilen yöntemleri kullanarak kimlik doğrulaması yapar. Kimlik doğrulama türünü yapılandırmak, her SqlPackage eyleminin (/SourceConnectionString ve /TargetConnectionString) bağlantı dizesi parametreleri aracılığıyla veya bağlantı özellikleri için tek tek parametreler aracılığıyla gerçekleştirilebilir. Bağlantı dizesinde aşağıdaki kimlik doğrulama yöntemleri desteklenir:

  • SQL Server kimlik doğrulaması
  • Active Directory (Windows) kimlik doğrulaması
  • Microsoft Entra doğrulaması
    • Kullanıcı adı/parola
    • Tümleşik kimlik doğrulaması
    • Evrensel kimlik doğrulaması
    • Yönetilen kimlik
    • Servis Principal

Denetim Altındaki Kimlik

Uyarı

Microsoft Entra Id daha önce Azure Active Directory (Azure AD) olarak biliniyordu.

Otomatikleştirilmiş ortamlarda, önerilen kimlik doğrulama yöntemi Microsoft Entra yönetilen kimliğidir . SqlPackage, Microsoft Entra kimlik doğrulamasını destekleyen veritabanlarına bağlanmak ve kimlik bilgileri yönetimi olmadan Microsoft Entra belirteçlerini almak için yönetilen kimlikleri kullandığı için, bu yöntem kimlik bilgilerinin çalışma zamanında SqlPackage'a geçirilmesini gerektirmez. Yönetilen kimlik, SqlPackage eyleminin çalıştırıldığı ortam için yapılandırıldığında, SqlPackage eylemi Azure SQL'de kimlik doğrulaması yapmak için bu kimliği kullanabilir. Ortamınız için yönetilen kimlik yapılandırma hakkında daha fazla bilgi için Yönetilen kimlik belgelerine bakın.

Sistem tarafından atanan yönetilen kimliği kullanan örnek bağlantı dizesi:

Server=sampleserver.database.windows.net; Authentication=Active Directory Managed Identity; Database=sampledatabase;

Yönetilen kimlikler hem Azure DevOps hem de GitHub eylemleri CI/CD işlem hatlarında desteklenir.

Servis Principal

Uyarı

Microsoft Entra Id daha önce Azure Active Directory (Azure AD) olarak biliniyordu.

Microsoft Entra uygulama hizmet sorumluları , belirli bir kiracıda bir uygulamanın neler yapabileceğini tanımlayan bir Microsoft Entra uygulaması içindeki güvenlik nesneleridir. Uygulama kayıt işlemi sırasında Azure portalında ayarlanır ve Azure SQL gibi Azure kaynaklarına erişecek şekilde yapılandırılır. Ortamınız için hizmet sorumlusu yapılandırma hakkında daha fazla bilgi için Hizmet sorumlusu belgelerine bakın.

SqlPackage'ı hizmet sorumlusuyla kullanırken, bir erişim belirteci alabilir ve bunu SqlPackage'a geçirebilirsiniz. Erişim belirteci Azure PowerShell modülü veya Azure CLI kullanılarak alınabilir. Bu işlemde, çağırma sistemi belirteç yenileme veya geçersizleştirme üzerinde denetim sahibidir. Erişim belirteci, /at parametresi kullanılarak SqlPackage'a geçirilebilir.

# example export connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -ResourceUrl "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token

SqlPackage /at:$AccessToken /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Export /TargetFile:"C:\AdventureWorksLT.bacpac" \
    /SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"

Alternatif olarak, bağlantı dizesinde hizmet sorumlusu istemci kimliğini ve gizli anahtarını SqlPackage'a geçirebilirsiniz. Bağlantı dizesi biçimiAuthentication=Active Directory Service Principal; ve User Id=AppId; Password=<password> içerir. Bağlantı dizesinde /at hizmet sorumlusu kimlik bilgileri geçirildiğinde parametresi gerekli değildir ve SqlPackage işlem sırasında gerektiğinde kimlik doğrulamasını yeniler.

Hizmet sorumluları hem Azure DevOps hem de GitHub eylemleri CI/CD işlem hatlarında desteklenir.

Ortam değişkenleri

Bağlantı havuzu yönetimi

Bağlantı havuzu, ortam değişkeni CONNECTION_POOLING_ENABLEDolarak ayarlanarak True SqlPackage tarafından yapılan tüm bağlantılar için etkinleştirilebilir. Bu ayar, Microsoft Kimlik Doğrulama Kitaplığı (MSAL) tarafından sınırlamayı önlemek için Microsoft Entra kullanıcı adı ve parola bağlantılarıyla yapılan işlemler için önerilir.

Geçici dosyalar

SqlPackage işlemleri sırasında, tablo verileri sıkıştırmadan önce veya sıkıştırmadan sonra geçici dosyalara yazılır. Büyük veritabanları için bu geçici dosyalar önemli miktarda disk alanı kaplayabilir, ancak konumları belirtilebilir. Dışarı aktarma ve ayıklama işlemleri, SqlPackage'ın varsayılan değerini geçersiz kılmak için belirtilmesi gereken /p:TempDirectoryForTableData isteğe bağlı bir özellik içerir.

.NET API GetTempPath , SqlPackage içindeki varsayılan değeri belirlemek için kullanılır.

Windows için aşağıdaki ortam değişkenleri aşağıdaki sırayla denetleniyor ve var olan ilk yol kullanılıyor:

  1. Ortam değişkeni tarafından TMP belirtilen yol.
  2. Ortam değişkeni tarafından TEMP belirtilen yol.
  3. Ortam değişkeni tarafından USERPROFILE belirtilen yol.
  4. Windows dizini.

Linux ve macOS için, yol ortam değişkeninde TMPDIR belirtilmezse varsayılan yol /tmp/ kullanılır.

SqlPackage ve veritabanı kullanıcıları

Kapsanan veritabanı kullanıcıları SqlPackage işlemlerine dahil edilir. Ancak, tanımın parola bölümü SqlPackage tarafından rastgele oluşturulan bir dizeye ayarlanır, mevcut değer aktarılamaz. Yeni kullanıcının parolasının, .bacpac içe aktarılması veya .dacpac dağıtımından sonra güvenli bir değere sıfırlanması önerilir. Otomatik bir ortamda parola değerleri, SqlPackage'ı izleyen bir adımda Azure Key Vault gibi güvenli bir anahtar deposundan alınabilir.

Genişletilebilirlik

SqlPackage , Yönetilen Genişletilebilirlik Çerçevesi (MEF) aracılığıyla genişletilebilirliği destekler ve katkıda bulunanlar olarak adlandırılan özel bileşenler aracılığıyla gelişmiş senaryoları etkinleştirir. Bu uzantılar, SqlPackage'ın dosyaları nasıl yayımlayabileceğini .dacpac özelleştirerek ekiplerin standartları zorunlu kılmasına veya projeye özgü mantığı otomatikleştirmesine olanak tanır. Yayımlama işleminin bir parçası olarak, dağıtım planı oluşturulduktan sonra ancak plan yürütülmeden önce dağıtıma katkıda bulunanlar yürütülür. Bu katkıda bulunanlar, adım eklemek, kaldırmak veya yeniden sıralamak için bir DeploymentPlanModifier sınıf nesnesi kullanarak dağıtım planına erişebilir ve bunları değiştirebilir. Dağıtım genişletilebilirliğini kullanmaya başlamak için bkz. Veritabanı derlemesini ve dağıtımlarını özelleştirmek için dağıtım katkıda bulunanlarını kullanma.

SqlPackage, SqlPackage yürütülebilir dosyasıyla aynı dizindeki dinamik bağlantı kitaplıklarını (.dll dosyaları) ve isteğe bağlı komut satırı özelliği /p:AdditionalDeploymentContributorPathsaracılığıyla belirtilen konumları tarayarak katkıda bulunan derlemeleri bulur ve yükler. Bu, esnek özelleştirmeye olanak sağlarken, güvenlikle ilgili önemli noktalar da sağlar.

Önemli

SqlPackage çalışma zamanında dinamik bağlantı kitaplıklarını (.dll dosyaları) dinamik olarak yüklemek için MEF kullandığından, SqlPackage yürütülebilir dosyasıyla birlikte yerleştirilen tüm derlemeler dağıtım işleminin bir parçası olarak yürütülebilir. Kötü amaçlı bir aktör, rastgele kod yürüten değiştirilmiş veya yetkisiz uzantılar sunarak bu davranıştan yararlanabilir.

SqlPackage ile kullanılan tüm derlenmiş uzantı dosyalarının güvenli olduğundan ve güvenilir kaynaklardan geldiğinden emin olmak sizin sorumluluğunuzdadır. SqlPackage klasörüne erişimi denetlemenizi ve tüm özel veya üçüncü taraf bileşenlerin bütünlüğünü doğrulamanızı öneririz.

Kullanım verileri toplama

SqlPackage, anonim özellik kullanımı ve tanılama verilerini toplayıp Microsoft'a gönderebilen İnternet özellikli özellikler içerir.

SqlPackage, Microsoft'a iletilebilen ve SqlPackage'ın kalitesini, güvenliğini ve güvenilirliğini artırmak için analiz edilebilen standart bilgisayar, kullanım ve performans bilgilerini toplayabilir.

SqlPackage kullanıcıya özgü veya kişisel bilgileri toplamaz. Tanılama amacıyla tek bir kullanıcıya yaklaşık olarak yardımcı olmak için, SqlPackage üzerinde çalıştığı her bilgisayar için rastgele bir GUID oluşturur ve bu değeri gönderdiği tüm olaylar için kullanır.

Ayrıntılar için bkz . Microsoft Gizlilik Bildirimi ve SQL Server Gizlilik eki.

Telemetri raporlamayı devre dışı bırakma

Telemetri toplama ve raporlamayı devre dışı bırakmak için ortam değişkenini DACFX_TELEMETRY_OPTOUT veya trueolarak 1 güncelleştirin.

Destek

DacFx kitaplığı ve SqlPackage CLI aracı Microsoft Modern Yaşam Döngüsü İlkesi'ni izler. Tüm güvenlik güncelleştirmeleri, düzeltmeler ve yeni özellikler yalnızca ana sürümün en son nokta sürümünde yayınlanıyor. DacFx veya SqlPackage yüklemelerinizi geçerli sürümde tutmak, tüm geçerli hata düzeltmelerini zamanında almanızı sağlamaya yardımcı olur.

DacFx GitHub deposunda SqlPackage ile ilgili yardım alın, özellik istekleri gönderin ve sorunları bildirin.

Desteklenen SQL teklifleri

SqlPackage ve DacFx, SqlPackage /DacFx sürümü sırasında desteklenen tüm SQL sürümlerini destekler. Örneğin, 14 Ocak 2022'deki bir SqlPackage sürümü, 14 Ocak 2022'de desteklenen tüm SQL sürümlerini destekler. SQL destek ilkeleri hakkında daha fazla bilgi için bkz. SQL destek ilkesi.

SqlPackage ve DacFx, SQL Server'a ek olarak Azure SQL Yönetilen Örneği, Azure SQL Veritabanı, Azure Synapse Analytics ve Doku Veri Ambarı'nı destekler.

Sonraki adımlar

  • Last updated on