Erstellen, Entwickeln und Validieren von SQL-Datenbankprojekten

Abgeschlossen

Bevor Sie Bereitstellungen automatisieren, Tests ausführen oder Schemaabweichungen erkennen können, benötigen Sie etwas, das eine Pipeline tatsächlich bauen kann. Das ist ein SQL-Datenbankprojekt.

Grundlegendes zu SQL-Datenbankprojekten

Stellen Sie sich ein SQL-Datenbankprojekt als Datenbank in Dateiform vor. Jede Tabelle, gespeicherte Prozedur, Ansicht und Funktion befindet sich in einer eigenen .sql Datei. Sie deklarieren jedes Objekt einmal, und wenn Sie eine Spalte hinzufügen oder einen Datentyp ändern müssen, bearbeiten Sie diese einzelne Datei.

Wenn Sie zuvor mit Migrationsskripts gearbeitet haben, ist der Unterschied signifikant. Migrationsskripts sind sequenziell. Sie schreiben eine ALTER Aussage, hoffen, dass sie in der richtigen Reihenfolge ausgeführt wird und sich im Laufe der Zeit eine wachsende Kette von Änderungen sammelt. Ein SQL-Datenbankprojekt verfolgt den gegenteiligen Ansatz: Sie behalten den gewünschten Endzustand jedes Objekts bei, und die Tools berechnen den Unterschied zwischen dem Projekt und der Zieldatenbank zur Bereitstellungszeit.

Beim Erstellen des Projekts ist die Ausgabe eine .dacpac Datei, ein kompiliertes Modell des gesamten Datenbankschemas. Sie veröffentlichen die .dacpac Datenbank, um eine neue Datenbank zu erstellen oder eine vorhandene datenbank zu aktualisieren. Der Buildprozess bietet Ihnen zwei Dinge, die für CI/CD wichtig sind:

• Überprüfung: Objektverweise und T-SQL-Syntax werden anhand einer bestimmten SQL-Version überprüft, bevor etwas bereitgestellt wird.
• Ein verteilbares Artefakt: Das .dacpac wird das einzelne Paket, das durch Ihre Pipeline in jede Umgebung gelangt.

Wählen Sie zwischen ursprünglichen und SDK-Stilprojekten aus

SQL-Datenbankprojekte werden in zwei Formaten erstellt. Das ursprüngliche Format basiert auf MSBuild (.NET Framework) und wird mit SQL Server Data Tools (SSDT) in Visual Studio ausgeliefert. Das SDK-Format basiert auf dem Microsoft.Build.Sql Projekt-SDK und ist das Format, das von der SQL-Datenbankprojekterweiterung für Visual Studio Code verwendet wird.

Für neue Projekte können Sie den SDK-Stil verwenden. Es bietet Funktionen, die das ursprüngliche Format nicht hat:

• .NET 8+-Unterstützung, sodass Sie plattformübergreifend unter Windows, Linux und macOS erstellen können. Diese Unterstützung ist wichtig, wenn Ihre CI-Läufer keine Windows-Computer sind.
• NuGet-Paketverweise für Datenbankverweise , sodass die Abhängigkeitsverwaltung den gleichen Mustern wie der Rest des .NET-Ökosystems folgt.
• Standard-Globbing für .sql Dateien. Legen Sie eine Datei im Projektordner ab, und sie wird automatisch im Build enthalten. Es sind keine manuellen Dateieinträge erforderlich.

Wenn Sie über ein ursprüngliches Projekt verfügen, können Sie es in sdk-formatieren, indem Sie die .sqlproj Datei ändern. Bevor Sie das Projekt konvertieren, sichern Sie die Projektdatei und archivieren Sie eine .dacpac Datei aus dem aktuellen Projekt. Vergleichen Sie .dacpac vorher und nachher, um zu überprüfen, ob nach der Konvertierung alles bewahrt wurde.

Hinweis

SQL-Projekte im SDK-Stil sind in Visual Studio Code und in der Vorschau in Visual Studio 2022 allgemein verfügbar. Visual Studio 2026 unterstützt nur das ursprüngliche SQL-Projektformat.

Erstellen und Auffüllen eines Projekts

Sie können ein SQL-Datenbankprojekt aus Visual Studio Code, Visual Studio oder der Befehlszeile erstellen. Die Befehlszeile eignet sich besonders für CI/CD-Szenarien, in denen keine grafische Umgebung verfügbar ist.

So erstellen Sie ein neues SDK-Formatprojekt:

dotnet new sqlproj -n MyDatabaseProject

📝 Dadurch wird eine .sqlproj Datei mit dem SDK-Format generiert. Von hier aus fügen Sie Datenbankobjekte hinzu, indem Sie Dateien in den Projektordner ablegen .sql . Das Standard Globbing-Muster nimmt sie automatisch auf.

Um beispielsweise eine Tabelle zu definieren, erstellen Sie 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
);

Beginnen Sie mit einer vorhandenen Datenbank? Mithilfe von Schemavergleichstools können Sie eine Livedatenbank mit einem leeren Projekt vergleichen und die Unterschiede importieren, sodass Sie nicht jedes Objekt manuell neu erstellen müssen.

Erstellen und Überprüfen des Projekts

Das Gebäude ist der Ort, an dem das Sicherheitsnetz einsetzt. Der Buildprozess überprüft jeden Objektverweis und überprüft die T-SQL-Syntax auf der Zielplattform. Wenn eine Ansicht auf eine Spalte verweist, die nicht vorhanden ist, schlägt der Build fehl. Wenn Sie eine in SQL Server 2025 hinzugefügte Vektorfunktion verwenden, ihr Projekt jedoch auf SQL Server 2017 (Sql140) ausgerichtet ist, wird sie vom Build erfasst.

So entwickeln Sie über die Befehlszeile:

dotnet build MyDatabaseProject.sqlproj

📝 Der Build erzeugt standardmäßig eine .dacpac Datei im bin/Debug Ordner.

Die Buildausgabe enthält Fehler (die den Build blockieren) und Warnungen (z. B. inkonsistente Groß- und Kleinschreibung in Objektnamen). Warnungen stoppen den Build nicht, sollten jedoch beachtet werden. Sie können SQL-Codeanalyseregeln auch aktivieren, um Verstöße gegen bewährte Methoden während des Builds zu kennzeichnen und Probleme wie veraltete Verknüpfungssyntax, SELECT * in Ansichten oder nicht indizierte Spalten in IN Prädikaten abzufangen.

Die Zielplattform wird in der .sqlproj-Datei festgelegt und steuert, welche T-SQL-Features validiert werden. Legen Sie sie so fest, dass sie Ihrem Bereitstellungsziel entspricht, unabhängig davon, ob es sich um SQL Server 2025- oder Azure SQL-Datenbank handelt.

Bereitstellen des Projekts

Sobald Sie ein .dacpac haben, übernimmt SqlPackage die Bereitstellung. Installieren Sie es als globales .NET-Tool:

dotnet tool install --global microsoft.sqlpackage

Veröffentlichen Sie dann in einer Zieldatenbank:

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

📝 SqlPackage ist plattformübergreifend und wird unter Windows, Linux und macOS ausgeführt.

Was während der Bereitstellung geschieht, hängt vom Ziel ab. Bei einer neuen Datenbank navigiert SqlPackage durch das Objektabhängigkeitsdiagramm und erstellt jedes Objekt in der richtigen Reihenfolge, beispielsweise zuerst die referenzierten Tabellen und danach die Fremdschlüssel. Bei einer vorhandenen Datenbank berechnet sie den Diff zwischen dem .dacpac und dem Liveschema und generiert dann nur die Anweisungen, die ALTER zum Schließen der Lücke erforderlich sind. Fehlende zwei Spalten? Sie erhalten eine ALTER TABLE mit beiden Ergänzungen. Der Prozess ist idempotent. Stellen Sie die gleichen .dacpac fünf Male bereit, und die fünfte Ausführung ändert nichts. Sie können auch ein einzelnes .dacpac über eine Flotte von Datenbanken verteilen, wenn Sie mehrere Mandanten aktualisieren.

Bevor Sie direkt bereitstellen, können Sie eine Vorschau der geplanten Änderungen anzeigen:

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

Die Script Aktion erzeugt den genauen T-SQL-Code, der ausgeführt werden würde. Die DeployReport Aktion erzeugt eine XML-Zusammenfassung jedes CREATE, ALTER und DROP. Überprüfen Sie eine der Umgebungen, bevor Sie Änderungen in die Produktion überführen.

Wichtige Erkenntnisse

Ein SQL-Datenbankprojekt speichert jedes Datenbankobjekt als deklarative .sql Datei, und der Build kompiliert sie in einem einzelnen .dacpac Artefakt. SDK-Stilprojekte (Microsoft.Build.Sql) unterstützen .NET 8+, plattformübergreifende Builds, NuGet-Paketverweise und Standard-Globbing für .sql Dateien. Der Buildprozess überprüft Objektverweise und T-SQL-Syntax anhand der Zielplattform, bevor eine Datenbank erreicht wird. SqlPackage berechnet den Unterschied zwischen der .dacpac und der Zieldatenbank und generiert nur die Anweisungen, die erforderlich sind, um die Lücke zu schließen. Verwenden Sie Script und DeployReport-Aktionen, um vor der Bereitstellung zur Produktion eine Vorschau geplanter Änderungen anzuzeigen. Das SQL-Datenbankprojekt, sein .dacpac Artefakt und SqlPackage bilden die Grundlage für alles, einschließlich Quellcodeverwaltung, CI/CD-Pipelines, Schemaabweichungserkennung und Tests.