Créer, générer et valider des projets SQL Database

Effectué

Avant de pouvoir automatiser les déploiements, exécuter des tests ou détecter la dérive de schéma, vous avez besoin de quelque chose que le pipeline puisse réellement construire. Il s’agit d’un projet de base de données SQL.

Comprendre les projets de base de données SQL

Considérez un projet de base de données SQL comme votre base de données sous forme de fichier. Chaque table, procédure stockée, vue et fonction réside dans son propre .sql fichier. Vous déclarez chaque objet une fois, et quand vous devez ajouter une colonne ou modifier un type de données, vous modifiez ce fichier unique.

Si vous avez déjà travaillé avec des scripts de migration, la différence est significative. Les scripts de migration sont séquentiels. Vous écrivez une ALTER instruction, espérez qu'elle s'exécute dans l'ordre approprié et accumulez une chaîne croissante de changements au fil du temps. Un projet de base de données SQL adopte l’approche opposée : vous conservez l’état final souhaité de chaque objet, et l’outil calcule la différence entre le projet et la base de données cible au moment du déploiement.

Lorsque vous générez le projet, la sortie est un .dacpac fichier, un modèle compilé de l’ensemble de votre schéma de base de données. Vous publiez cela .dacpac pour créer une base de données ou mettre à jour une base de données existante. Le processus de compilation fournit deux éléments essentiels pour le CI/CD :

• Validation : les références d’objet et la syntaxe T-SQL sont vérifiées par rapport à une version spécifique de SQL avant tout déploiement.
• Artefact déployable : le .dacpac package devient le package unique qui transite par votre pipeline vers chaque environnement.

Choisir entre les projets d'origine et ceux de style SDK

Les projets de base de données SQL sont fournis dans deux formats. Le format d’origine est basé sur MSBuild (.NET Framework) et est fourni avec SQL Server Data Tools (SSDT) dans Visual Studio. Le format de style SDK est basé sur le SDK du Microsoft.Build.Sql projet et est le format utilisé par l’extension Projets SQL Database pour Visual Studio Code.

Pour les nouveaux projets, utilisez le style sdk. Il offre des fonctionnalités dont le format d’origine n’a pas :

• Prise en charge de .NET 8+, vous permettant de développer en multiplateforme sur Windows, Linux et macOS. Cette prise en charge est importante lorsque vos exécuteurs CI ne sont pas des machines Windows.
• Références de package NuGet pour les références de base de données. Par conséquent, la gestion des dépendances suit les mêmes modèles que le reste de l’écosystème .NET.
• Globbing par défaut pour les fichiers .sql. Supprimez un fichier dans le dossier du projet et il est automatiquement inclus dans la build. Aucune entrée de fichier manuelle n’est nécessaire.

Si vous avez un projet d’origine existant, vous pouvez le convertir en style SDK en modifiant le .sqlproj fichier. Avant de convertir le projet, sauvegardez le fichier du projet et archivez un élément .dacpac à partir du projet actuel. Comparez un « avant » et un « après » .dacpac pour confirmer que la conversion a tout conservé.

Note

Les projets SQL de style SDK sont généralement disponibles dans Visual Studio Code et en préversion dans Visual Studio 2022. Visual Studio 2026 prend uniquement en charge le format de projet SQL d’origine.

Créer et remplir un projet

Vous pouvez créer un projet de base de données SQL à partir de Visual Studio Code, de Visual Studio ou de la ligne de commande. La ligne de commande est particulièrement pratique pour les scénarios CI/CD où aucun environnement graphique n’est disponible.

Pour créer un projet de style SDK :

dotnet new sqlproj -n MyDatabaseProject

📝 Cela génère un .sqlproj fichier au format de style SDK. À partir de là, vous ajoutez des objets de base de données en déposant les fichiers .sql dans le dossier du projet. Le modèle de globbing par défaut les inclut automatiquement.

Par exemple, pour définir une table, créez 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
);

À partir d’une base de données existante ? Les outils de comparaison de schémas vous permettent de comparer une base de données dynamique à un projet vide et d’importer les différences. Vous n’avez donc pas besoin de recréer chaque objet à la main.

Générer et valider le projet

La construction est le moment où le filet de sécurité entre en action. Le processus de génération valide chaque référence d’objet et vérifie la syntaxe T-SQL sur la plateforme cible. Si une vue fait référence à une colonne qui n’existe pas, la build échoue. Si vous utilisez une fonction vectorielle ajoutée dans SQL Server 2025, mais que votre projet cible SQL Server 2017 (Sql140), la build l’intercepte.

Pour générer à partir de la ligne de commande :

dotnet build MyDatabaseProject.sqlproj

📝 La build produit un .dacpac fichier dans le bin/Debug dossier par défaut.

La sortie de compilation comprend les erreurs, qui bloquent le processus, ainsi que les avertissements, tels que les incohérences de majuscules dans les noms d’objets. Les avertissements n’interrompent pas la compilation, mais ils méritent une attention particulière. Vous pouvez également activer les règles d’analyse du code SQL pour signaler les violations de bonnes pratiques pendant la génération, en interceptant des problèmes tels que la syntaxe de jointure déconseillée, SELECT * dans les vues ou les colonnes non indexées dans les IN prédicats.

La plateforme cible est définie dans le fichier .sqlproj et contrôle les fonctionnalités T-SQL qui passent la validation. Définissez-le pour qu’il corresponde à votre cible de déploiement, que ce soit SQL Server 2025 ou Azure SQL Database.

Déployer le projet

Une fois que vous avez un .dacpac, SqlPackage gère le déploiement. Installez-le en tant qu’outil global .NET :

dotnet tool install --global microsoft.sqlpackage

Publiez ensuite sur une base de données cible :

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

📝 SqlPackage est multiplateforme et s’exécute sur Windows, Linux et macOS.

Ce qui se passe pendant le déploiement dépend de la cible. Pour une nouvelle base de données, SqlPackage navigue dans le graphique des dépendances d’objet et crée chaque objet dans l’ordre correct, comme les tables référencées avant les clés étrangères. Pour une base de données existante, elle calcule la différence entre le .dacpac et le schéma en direct, puis génère uniquement les ALTER instructions nécessaires pour combler la différence. Deux colonnes manquantes ? Vous obtenez un ALTER TABLE qui inclut les deux ajouts. Le processus est idempotent. Déployez les mêmes .dacpac cinq fois et la cinquième exécution ne change rien. Vous pouvez également distribuer un unique .dacpac sur un ensemble de bases de données lors de la mise à niveau de plusieurs locataires

Avant de déployer directement, vous pouvez afficher un aperçu des modifications planifiées :

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

L’action Script produit le T-SQL exact qui s’exécuterait. L’action DeployReport produit un résumé XML de chaque CREATE, ALTERet DROP. Passez en revue l’une ou l’autre avant d’envoyer des modifications à la production.

Points clés à prendre

Un projet de base de données SQL stocke chaque objet de base de données sous forme de fichier déclaratif .sql et la build les compile en un seul .dacpac artefact. Les projets de style SDK (Microsoft.Build.Sql) prennent en charge .NET 8+, les builds multiplateformes, les références de package NuGet et le globbing par défaut pour les fichiers .sql. Le processus de génération valide les références d’objet et la syntaxe T-SQL par rapport à la plateforme cible avant d’atteindre une base de données. SqlPackage calcule la différence entre .dacpac et la base de données cible, générant uniquement les instructions nécessaires pour combler l'écart. Utilisez les actions Script et DeployReport pour afficher un aperçu des modifications planifiées avant de les déployer en production. Le projet de base de données SQL, son .dacpac artefact et SqlPackage constituent la base de tout ce qui précède, notamment le contrôle de code source, les pipelines CI/CD, la détection de dérive de schéma et les tests.