Sdílet prostřednictvím

SqlPackage

SqlPackage je nástroj příkazového řádku, který automatizuje úlohy vývoje databáze zveřejněním některých veřejných rozhraní API Data-Tier Application Framework (DacFx). Primární případy použití sqlPackage se zaměřují na přenositelnost a nasazení databází pro SQL Server, Azure SQL a řadu databází Azure Synapse Analytics. SqlPackage je možné automatizovat pomocí Azure Pipelines a GitHub Actions nebo jiných nástrojů CI/CD.

Stáhněte si nejnovější verzi. Podrobnosti o nejnovější verzi najdete v poznámkách k verzi.

Poznámka:

I když je ID Microsoft Entra novým názvem služby Azure Active Directory (Azure AD), aby se zabránilo narušení existujících prostředí, Azure AD stále zůstává v některých pevně zakódovaných prvcích, jako jsou pole uživatelského rozhraní, poskytovatelé připojení, kódy chyb a rutiny. V tomto článku jsou tyto dva názvy zaměnitelné.

Přenosnost

Přenositelnost databáze je schopnost přesouvat schéma databáze a data mezi různými instancemi SQL Serveru, Azure SQL a Azure Synapse Analytics. Příkladem přenositelnosti databáze je export databáze z Azure SQL Database do místní instance SQL Serveru nebo z SQL Serveru do Azure SQL Database. SqlPackage podporuje přenositelnost databáze prostřednictvím akcí exportu a importu , které vytvářejí a využívají soubory BACPAC. SqlPackage také podporuje přenositelnost databáze prostřednictvím akcí extrakce a publikování , které vytvářejí a využívají soubory DACPAC, které mohou obsahovat data přímo nebo odkazovat data uložená ve službě Azure Blob Storage.

  • Export: Exportuje připojenou databázi SQL včetně schématu databáze a uživatelských dat do souboru BACPAC (.bacpac).

  • Import: Importuje data schématu a tabulky ze souboru BACPAC do nové uživatelské databáze.

Nasazení

Nasazení databáze je proces aktualizace schématu databáze tak, aby odpovídal požadovanému stavu, například přidání sloupců do tabulky nebo změna obsahu uložené procedury. SqlPackage podporuje nasazení databáze prostřednictvím akcí Publikování a extrakce . Akce Publikovat aktualizuje schéma databáze tak, aby odpovídalo obsahu zdrojového souboru .dacpac, zatímco akce extrakce vytvoří soubor aplikace datové vrstvy (.dacpac) obsahující schéma nebo schéma a uživatelská data z připojené databáze SQL. SqlPackage umožňuje nasazení proti novým nebo existujícím databázím ze stejného artefaktu (.dacpac) tím, že automaticky vytvoří plán nasazení, který použije potřebné změny v cílové databázi. Plán nasazení je možné zkontrolovat před použitím změn v cílové databázi pomocí akcí Script nebo DeployReport .

  • Extrakce: Vytvoří soubor aplikace datové vrstvy (.dacpac), který obsahuje schéma nebo schéma s uživatelskými daty z připojené SQL databáze.

  • Publikování: Přírůstkově aktualizuje schéma databáze tak, aby odpovídalo schématu zdrojového souboru .dacpac. Pokud databáze na serveru neexistuje, operace publikování ji vytvoří. V opačném případě se aktualizuje existující databáze.

  • DeployReport: Vytvoří sestavu XML představující změny, které provede akce publikování.

  • DriftReport: Vytvoří sestavu XML představující změny použité u registrované databáze od poslední registrace.

  • Skript: Vytvoří inkrementální aktualizační skript Transact-SQL, který přizpůsobí schéma cíle tak, aby odpovídalo schématu zdroje.

Syntaxe Command-Line

SqlPackage inicializuje akce zadané pomocí parametrů, vlastností a proměnných SQLCMD zadaných na příkazovém řádku.

SqlPackage {parameters} {properties} {SQLCMD variables}

Další informace o syntaxi příkazového řádku SqlPackage najdete v referenčních informacích k rozhraní příkazového řádku SqlPackage a jednotlivých stránkách akcí.

Příkazy nástroje

Verze

Zobrazí verzi sqlpackage jako číslo buildu. Lze použít ve interaktivních výzvách a v automatizovaných kanálech.

SqlPackage /Version

Pomoc

Informace o využití SqlPackage můžete zobrazit pomocí /? nebo /help:True.

SqlPackage /?

Pro získání informací o parametrech a vlastnostech souvisejících s konkrétní akcí použijte spolu s parametrem dané akce také parametr nápovědy.

SqlPackage /Action:Publish /?

Autentizace

SqlPackage se ověřuje pomocí metod dostupných v SqlClient. Konfiguraci typu ověřování lze provést prostřednictvím parametrů připojovacího řetězce pro každou akci SqlPackage (/SourceConnectionString a /TargetConnectionString) nebo prostřednictvím jednotlivých parametrů pro vlastnosti připojení. Připojovací řetězec podporuje následující metody ověřování:

  • Ověřování SQL Serveru
  • Ověřování Active Directory (Windows)
  • Ověřování Microsoft Entra
    • Uživatelské jméno a heslo
    • Integrované ověřování
    • Univerzální ověřování
    • Spravovaná identita
    • Hlavní služba

Spravovaná identita

Poznámka:

Microsoft Entra ID se dříve označovala jako Azure Active Directory (Azure AD).

V automatizovaných prostředích je doporučenou metodou autentizace Microsoft Entra managed identity. Tato metoda nevyžaduje předávání přihlašovacích údajů sqlPackage za běhu, protože SqlPackage používá spravované identity pro připojení k databázím, které podporují ověřování Microsoft Entra, a k získání tokenů Microsoft Entra bez správy přihlašovacích údajů. Pokud je spravovaná identita nakonfigurovaná pro prostředí, ve kterém je spuštěna akce SqlPackage, může akce SqlPackage tuto identitu použít k ověření v Azure SQL. Další informace o konfiguraci spravované identity pro vaše prostředí najdete v dokumentaci ke spravované identitě.

Příkladem připojovacího řetězce, který používá spravovanou identitu přiřazenou systémem, je:

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

Spravované identity jsou podporovány jak v CI/CD kanálech Azure DevOps, tak v GitHub Actions.

Hlavní služba

Poznámka:

Microsoft Entra ID se dříve označovala jako Azure Active Directory (Azure AD).

Instanční objekty aplikace Microsoft Entra jsou objekty zabezpečení v aplikaci Microsoft Entra, které definují, co může aplikace v daném tenantovi dělat. Nastaví se na webu Azure Portal během procesu registrace aplikace a nakonfiguruje se pro přístup k prostředkům Azure, jako je Azure SQL. Další informace o konfiguraci aplikačního objektu pro vaše prostředí najdete v dokumentaci aplikačního objektu.

Při použití SqlPackage s principálem služby můžete načíst přístupový token a předat ho SqlPackage. Přístupový token je možné načíst pomocí modulu Azure PowerShellu nebo Azure CLI. V tomto procesu si vyvolávající systém udržuje kontrolu nad aktualizací nebo zneplatněním tokenu. Přístupový token lze předat sqlPackage pomocí parametru /at .

# 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;"

Alternativně můžete předat ID klienta služebního principála a tajný klíč do SqlPackage v připojovacím řetězci. Formát připojovacího řetězce zahrnuje Authentication=Active Directory Service Principal; a User Id=AppId; Password=<password>. Pokud jsou přihlašovací údaje služebního principálu předány v připojovacím řetězci, /at parametr není vyžadován a SqlPackage aktualizuje ověřování v průběhu operace podle potřeby.

Služební principály jsou podporovány v kanálech CI/CD Azure DevOps i GitHub Actions.

Proměnné prostředí

Sdružování připojení

Sdružování připojení lze povolit pro všechna připojení vytvořená nástrojem SqlPackage nastavením proměnné prostředí CONNECTION_POOLING_ENABLED na True hodnotu. Toto nastavení se doporučuje pro operace s uživatelským jménem a heslem microsoft Entra, aby se zabránilo omezování knihovnou MICROSOFT Authentication Library (MSAL).

Dočasné soubory

Během operací SqlPackage se data tabulky zapisuje do dočasných souborů před kompresí nebo po dekompresi. U velkých databází mohou tyto dočasné soubory zabírat značné množství místa na disku, ale jejich umístění lze zadat. Operace exportu a extrakce zahrnují volitelnou vlastnost, která umožňuje specifikovat hodnotu /p:TempDirectoryForTableData, aby přepsala výchozí hodnotu SqlPackage.

Rozhraní .NET API GetTempPath slouží k určení výchozí hodnoty v rámci sqlPackage.

Pro Windows jsou následující proměnné prostředí kontrolovány v následujícím pořadí a použita je první cesta, která existuje:

  1. Cesta určená proměnnou TMP prostředí.
  2. Cesta určená proměnnou TEMP prostředí.
  3. Cesta určená proměnnou USERPROFILE prostředí.
  4. Adresář Systému Windows.

Pokud v linuxu a macOS není cesta zadaná v TMPDIR proměnné prostředí, použije se výchozí cesta /tmp/ .

Uživatelé sqlPackage a databáze

Uživatelé databáze s omezením jsou součástí operací SqlPackage. Nicméně, část definice hesla je nastavena na náhodně vygenerovaný řetězec prostřednictvím SqlPackage, takže stávající hodnota se nepřenese. Doporučuje se resetovat heslo nového uživatele na zabezpečenou hodnotu po importu .bacpac nebo nasazení .dacpac. V automatizovaném prostředí je možné hodnoty hesel načíst ze zabezpečeného úložiště klíčů, jako je Azure Key Vault, v kroku následujícího po sqlPackage.

Rozšiřitelnost

SqlPackage podporuje rozšiřitelnost prostřednictvím rozhraní MEF (Managed Extensibility Framework) a umožňuje pokročilé scénáře prostřednictvím vlastních komponent označovaných jako přispěvatelé. Tato rozšíření můžou přizpůsobit, jak SqlPackage publikuje .dacpac soubory, což týmům umožňuje vynucovat standardy nebo automatizovat logiku specifickou pro projekt. Komponenty nasazení jsou vykonávány jako součást publikačního procesu po vygenerování plánu nasazení, ale před jeho spuštěním. Tito přispěvatelé můžou přistupovat k plánu nasazení a upravovat ho pomocí objektu DeploymentPlanModifier třídy a přidávat, odebírat nebo měnit pořadí kroků. Pokud chcete začít s rozšiřitelností nasazení, přečtěte si téma Použití přispěvatelů nasazení k přizpůsobení sestavení a nasazení databáze.

SqlPackage vyhledá a načte sestavení přispěvatele vyhledáním dynamických knihoven (.dll souborů) ve stejném adresáři jako spustitelný soubor SqlPackage a na umístěních zadaných prostřednictvím volitelné vlastnosti příkazového řádku /p:AdditionalDeploymentContributorPaths. I když to umožňuje flexibilní přizpůsobení, přináší také důležité aspekty zabezpečení.

Důležité

Vzhledem k tomu, že SqlPackage používá MEF k dynamickému načítání dynamických knihoven (.dll souborů) za běhu, může být jakékoli sestavení umístěné společně se spustitelným souborem SqlPackage spuštěno jako součást procesu nasazení. Škodlivý útočník by mohl toto chování zneužít zavedením pozměněných či neoprávněných rozšíření, která spouštějí libovolný kód.

Je vaší zodpovědností zajistit, aby všechny kompilované soubory rozšíření používané s SqlPackage byly zabezpečené a pocházejí z důvěryhodných zdrojů. Doporučujeme řídit přístup ke složce SqlPackage a ověřovat integritu všech vlastních komponent nebo komponent třetích stran.

Shromažďování dat o využití

SqlPackage obsahuje funkce s podporou internetu, které můžou shromažďovat a odesílat anonymní používání funkcí a diagnostická data do Microsoftu.

SqlPackage může shromažďovat standardní informace o počítači, používání a výkonu, které mohou být přenášeny do Microsoftu a analyzovány za účelem zlepšení kvality, zabezpečení a spolehlivosti sqlPackage.

SqlPackage neshromažďuje konkrétní uživatele ani osobní údaje. SqlPackage pro účely diagnostiky pomáhá odhadnout jednoho uživatele a vygeneruje náhodný identifikátor GUID pro každý počítač, na kterém běží, a použije tuto hodnotu pro všechny události, které odesílá.

Podrobnosti najdete v prohlášení o zásadách ochrany osobních údajů společnosti Microsoft a dodatku k prohlášení o zásadách ochrany osobních údajů pro SQL Server.

Zakázat odesílání telemetrie

Chcete-li zakázat shromažďování a generování sestav telemetrie, aktualizujte proměnnou DACFX_TELEMETRY_OPTOUT prostředí na true nebo 1.

Podpora

Knihovna DacFx a nástroj SqlPackage CLI se řídí moderními zásadami životního cyklu Společnosti Microsoft. Všechny aktualizace zabezpečení, opravy a nové funkce se vydávají pouze v nejnovější verzi hlavní verze. Udržování instalací DacFx nebo SqlPackage na aktuální verzi pomáhá zajistit, že obdržíte všechny příslušné opravy chyb včas.

Získejte nápovědu k SqlPackage, odesílání žádostí o funkce a hlášení problémů v úložišti DacFx Na GitHubu.

Podporované nabídky SQL

SqlPackage a DacFx podporují všechny podporované verze SQL v době vydání SqlPackage/DacFx. Například verze SqlPackage 14. ledna 2022 podporuje všechny podporované verze SQL v lednu 14 2022. Další informace o zásadách podpory SQL najdete v zásadách podpory SQL.

Kromě SQL Serveru podporuje SqlPackage a DacFx azure SQL Managed Instance, Azure SQL Database, Azure Synapse Analytics a Fabric Data Warehouse.

Další kroky

  • Last updated on