Vytvoření, sestavení a ověření projektů SQL databáze

Než budete moct automatizovat nasazení, spouštět testy nebo zjišťovat odchylky ve schématu, potřebujete něco, co může pipeline skutečně sestavit. To je projekt databáze SQL.

Principy projektů databáze SQL

Projekt databáze SQL si můžete představit jako databázi ve formě souboru. Každá tabulka, uložená procedura, zobrazení a funkce se nachází ve vlastním .sql souboru. Každý objekt deklarujete jednou a když potřebujete přidat sloupec nebo změnit datový typ, upravíte tento jeden soubor.

Pokud jste dříve pracovali se skripty migrace, je rozdíl významný. Skripty migrace jsou sekvenční. Napíšete ALTER příkaz, doufáte, že poběží ve správném pořadí, a postupně se hromadí řetězec změn. Projekt databáze SQL používá opačný přístup: udržujete požadovaný koncový stav každého objektu a nástroj vypočítá rozdíl mezi projektem a cílovou databází v době nasazení.

Při sestavování projektu je výstupem .dacpac soubor, zkompilovaný model celého schématu databáze. Publikujete ji .dacpac a vytvoříte novou databázi nebo aktualizujete existující databázi. Proces sestavení vám poskytne dvě věci, které jsou důležité pro CI/CD:

• Ověřování: Odkazy na objekty a syntaxe T-SQL se před nasazením čehokoli kontrolují na konkrétní verzi SQL.
• Nasaditelný artefakt: stane .dacpac se jediným balíčkem, který prochází kanálem do každého prostředí.

Volba mezi původními projekty a projekty ve stylu sady SDK

Projekty databáze SQL mají dva formáty. Původní formát je založený na msBuildu (.NET Framework) a dodává se s SQL Server Data Tools (SSDT) v sadě Visual Studio. Formát stylu sady SDK je založený na Microsoft.Build.Sql sadě SDK projektu a je formát používaný rozšířením projektů SQL Database pro Visual Studio Code.

U nových projektů zvolte SDK styl. Přináší funkce, které původní formát neobsahuje:

• Podpora .NET 8 a novější, takže můžete vytvářet různé platformy ve Windows, Linuxu a macOS. Tato podpora je důležitá, když vaše spouštěče CI nejsou počítače s Windows.
• Odkazy na balíčky NuGet pro odkazy na databáze, takže správa závislostí se řídí stejnými vzory jako zbytek ekosystému .NET.
• Výchozí globbing pro .sql soubory Zahoďte soubor do složky projektu a automaticky se zahrne do sestavení. Není potřeba žádné ruční zadávání souborů.

Pokud máte existující původní projekt, můžete ho převést na styl sady SDK úpravou .sqlproj souboru. Před převodem projektu zálohujte soubor projektu a archivujte soubor .dacpac z aktuálního projektu. Porovnejte "před" a "po" .dacpac a potvrďte, že převod zůstal zachován.

Vytvoření a naplnění projektu

Projekt databáze SQL můžete vytvořit pomocí editoru Visual Studio Code, sady Visual Studio nebo příkazového řádku. Příkazový řádek je užitečný zejména pro scénáře CI/CD, kde není k dispozici žádné grafické prostředí.

Vytvoření nového projektu ve stylu sady SDK:

dotnet new sqlproj -n MyDatabaseProject

📝 Tím se .sqlproj vygeneruje soubor ve formátu stylu sady SDK. Odtud přidáte databázové objekty přetažením .sql souborů do složky projektu. Výchozí vzor globbingu je automaticky vybere.

Pokud chcete například definovat tabulku, vytvořte Tables/Customers.sql:

CREATE TABLE [dbo].[Customers]
(
    [CustomerID] INT NOT NULL PRIMARY KEY,
    [FirstName] NVARCHAR(50) NOT NULL,
    [LastName] NVARCHAR(50) NOT NULL,
    [Email] NVARCHAR(100) NULL
);

Začínáte s existující databází? Nástroje pro porovnání schémat umožňují porovnat živou databázi s prázdným projektem a importovat rozdíly, takže nemusíte znovu vytvářet všechny objekty ručně.

Sestavení a ověření projektu

Budování je fáze, kde se uplatňuje bezpečnostní síť. Proces sestavení ověřuje všechny odkazy na objekty a kontroluje syntaxi T-SQL na cílové platformě. Pokud zobrazení odkazuje na sloupec, který neexistuje, sestavení selže. Pokud použijete vektorovou funkci přidanou v SQL Serveru 2025, ale váš projekt cílí na SQL Server 2017 (Sql140), sestavení ho zachytí.

Sestavení z příkazového řádku:

dotnet build MyDatabaseProject.sqlproj

📝 Sestavení ve výchozím nastavení vytvoří .dacpac soubor ve bin/Debug složce.

Výstup sestavení obsahuje chyby (které blokují sestavení) a upozornění (například nekonzistentní velikost písmen v názvech objektů). Upozornění nezastavují sestavení, ale stojí za to věnovat pozornost. Můžete také povolit pravidla analýzy kódu SQL, která při sestavování označí porušení osvědčených postupů, zachytí problémy, jako je zastaralá syntaxe spojení, SELECT * v zobrazeních nebo neindexovaných sloupcích v IN predikátech.

Cílová platforma je nastavena v .sqlproj souboru a řídí, které funkce T-SQL procházejí validací. Nastavte ho tak, aby odpovídal cíli nasazení, ať už je to SQL Server 2025 nebo Azure SQL Database.

Nasazení projektu

Jakmile budete mít .dacpac, SqlPackage zpracuje nasazení. Nainstalujte ho jako globální nástroj .NET:

dotnet tool install --global microsoft.sqlpackage

Pak publikujte do cílové databáze:

sqlpackage /Action:Publish /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"Server=myserver.database.windows.net;Database=mydb;Authentication=Active Directory Default"

📝 SqlPackage je multiplatformní a běží ve Windows, Linuxu a macOS.

Co se stane během nasazení, závisí na cíli. Pro novou databázi SqlPackage prochází graf závislostí objektu a vytvoří každý objekt ve správném pořadí, například odkazované tabulky před cizími klíči. U existující databáze vypočítá rozdíl mezi .dacpac živým schématem a pak vygeneruje pouze ALTER příkazy potřebné k zavření mezery. Chybí dva sloupce? Dostanete jeden ALTER TABLE s oběma dodatky. Proces je idempotentní. Nasaďte stejných .dacpac pětkrát a při pátém spuštění se nic nezmění. Při upgradu více tenantů můžete také rozšířit jednu .dacpac napříč flotilou databází.

Před přímým nasazením můžete zobrazit náhled plánovaných změn:

sqlpackage /Action:Script /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:deploy-script.sql
sqlpackage /Action:DeployReport /SourceFile:bin/Debug/MyDatabaseProject.dacpac /TargetConnectionString:"..." /OutputPath:report.xml

Akce Script vytvoří přesný T-SQL, který by byl spuštěn. Akce DeployReport vytvoří souhrn XML každého CREATE, ALTERa DROP. Před nasazením změn do produkčního prostředí zkontrolujte kteroukoliv z možností.

Klíčové poznatky

Projekt databáze SQL ukládá každý databázový objekt jako deklarativní .sql soubor a sestavení je zkompiluje do jednoho .dacpac artefaktu. Projekty ve stylu sady SDK (Microsoft.Build.Sql) podporují .NET 8+, víceplatformní sestavení, odkazy na balíčky NuGet a výchozí globbing pro soubory .sql. Proces sestavení ověří odkazy na objekty a syntaxi T-SQL na cílovou platformu předtím, než cokoli dosáhne databáze. SqlPackage vypočítá rozdíl mezi .dacpac cílovou databází a vygeneruje pouze příkazy potřebné k zavření mezery. Pomocí akcí Script a DeployReport si před nasazením do produkčního prostředí zobrazte náhled plánovaných změn. Projekt databáze SQL, jeho .dacpac artefakt a SqlPackage tvoří základ pro všechno dopředu, včetně správy zdrojového kódu, kanálů CI/CD, detekce odchylek schématu a testování.