Un DacPac est un fichier compressé avec l’extension .dacpac utilisé pour déployer, gérer et versionner des bases de données SQL Server ou Azure SQL Database. Il encapsule la définition complète du schéma de la base de données (tables, vues, procédures stockées, fonctions, types, etc.) sous forme de métadonnées XML, ainsi que des informations sur les objets dépendants.
Qu’est-ce qu’un DacPac ?
Structure détaillée d’un fichier DacPac
Un fichier .dacpac est en réalité une archive ZIP contenant plusieurs fichiers structurés :
- model.xml : le cœur du DacPac, ce fichier XML décrit l’ensemble du schéma de la base de données (objets, propriétés, relations).
- Origin.xml : informations sur l’origine du DacPac (outil et version ayant produit le package, date, checksums).
- DacMetadata.xml : nom et version de l’application data-tier.
- predeploy.sql / postdeploy.sql : scripts optionnels exécutés avant ou après le déploiement du schéma.
- Références : informations décrivant les dépendances vers d’autres bases ou packages.
Comme c’est un ZIP, on peut l’inspecter simplement :
# Renommer en .zip (ou utiliser Expand-Archive après copie) pour explorer le contenu
Copy-Item .\Boutique.Database.dacpac .\Boutique.zip
Expand-Archive .\Boutique.zip -DestinationPath .\dacpac-contenu
Get-ChildItem .\dacpac-contenu
Utilisations principales
- Déploiement initial : création d’une nouvelle base de données à partir du modèle contenu dans le DacPac.
- Mise à jour (upgrade) : comparaison du schéma du DacPac avec une base existante et génération automatique des scripts de migration nécessaires.
- Contrôle de version : le schéma (les fichiers
.sqldu projet) est versionné dans le système de gestion de code source pour suivre son évolution. - Automatisation DevOps : intégration dans des pipelines CI/CD pour automatiser les déploiements et les tests de schéma.
Une approche déclarative
La force du DacPac est d’être déclaratif (on parle d’approche state-based) : on décrit l’état cible de la base, et c’est l’outil qui calcule la différence avec la base existante pour produire le script ALTER adapté. C’est l’inverse des migrations EF Core (migration-based), où chaque changement est un script ordonné écrit (ou généré) à l’avance.
| Critère | DacPac (state-based) | Migrations EF Core (migration-based) |
|---|---|---|
| Source de vérité | Les fichiers CREATE du projet SQL |
La suite des migrations C# |
| Script de mise à jour | Calculé au moment du déploiement | Figé à la création de la migration |
| Base dans un état inconnu | Pas de problème : on compare | Risqué : l’historique doit correspondre |
| Objets SQL avancés (procédures, index filtrés, permissions) | Natif | Via migrationBuilder.Sql(...) |
| Renommages, transformations de données | À guider (refactorlog, scripts pre/post) | Explicites dans la migration |
| Profil type | Équipe avec DBA, base partagée entre plusieurs applications | Base possédée par une seule application .NET |
Avantages
- Automatisation : facilite le déploiement et la mise à jour des bases de données sans intervention manuelle.
- Sécurité : réduit les risques d’erreurs humaines lors des modifications de schéma.
- Traçabilité : permet de versionner précisément l’état du schéma à chaque étape du développement.
- Portabilité : simplifie la migration entre environnements (développement, test, production).
- Comparaison de schémas : outils intégrés pour comparer et synchroniser les différences entre le DacPac et une base cible.
- Validation à la compilation : une vue qui référence une colonne supprimée fait échouer le build, pas le déploiement en production.
Limites
- Pas de données : un DacPac ne contient que le schéma, pas les données de la base. Pour transporter schéma et données, il existe le format cousin BACPAC (actions
Export/Importde SqlPackage). Les données de référence se gèrent dans un script de post-déploiement. - Opérations complexes : certaines transformations majeures ou manipulations de données nécessitent des scripts personnalisés.
- Compatibilité : certaines fonctionnalités spécifiques à une version de SQL Server peuvent ne pas être entièrement supportées.
Créer un projet SQL SDK-style
Historiquement, les projets de base de données (.sqlproj) nécessitaient Visual Studio et SSDT pour être compilés. Le SDK Microsoft.Build.Sql apporte des projets « SDK-style », comme les projets C# modernes : un fichier projet court, tous les .sql du dossier inclus automatiquement, et surtout un build possible avec dotnet build, sur Windows, Linux ou macOS, donc dans n’importe quel agent de CI.
Création du projet
# Installer les templates de projets SQL
dotnet new install Microsoft.Build.Sql.Templates
# Créer le projet
dotnet new sqlproj -n Boutique.Database
Le fichier .sqlproj
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build">
<Sdk Name="Microsoft.Build.Sql" Version="2.3.0" />
<PropertyGroup>
<Name>Boutique.Database</Name>
<!-- Plateforme cible : ici SQL Server 2022 (Sql160) -->
<DSP>Microsoft.Data.Tools.Schema.Sql.Sql160DatabaseSchemaProvider</DSP>
<ModelCollation>1033, CI</ModelCollation>
<!-- Les avertissements T-SQL (ex : référence non résolue) cassent le build -->
<TreatTSqlWarningsAsErrors>True</TreatTSqlWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<!-- Scripts exécutés avant / après le déploiement du schéma.
Ils sont exclus automatiquement du modèle. -->
<PreDeploy Include="Scripts\PreDeployment.sql" />
<PostDeploy Include="Scripts\PostDeployment.sql" />
</ItemGroup>
<ItemGroup>
<!-- Variable SQLCMD, valorisable au déploiement (/v:Environnement=Prod) -->
<SqlCmdVariable Include="Environnement">
<DefaultValue>Dev</DefaultValue>
<Value>$(SqlCmdVar__1)</Value>
</SqlCmdVariable>
</ItemGroup>
</Project>
La propriété DSP détermine la plateforme cible : Sql150 pour SQL Server 2019, Sql160 pour 2022, SqlAzureV12 pour Azure SQL Database… Le build valide la syntaxe et les fonctionnalités par rapport à cette plateforme.
Si le schéma référence des objets système (
sys.objects, procédures demaster…), on ajoute une référence au package NuGetMicrosoft.SqlServer.Dacpacs.Masterpour que ces références soient résolues au build.
Les objets de la base
Chaque objet est décrit par son ordre CREATE, un fichier par objet, rangés par schéma et type :
Boutique.Database/
├── Boutique.Database.sqlproj
├── dbo/
│ ├── Tables/
│ │ ├── Categorie.sql
│ │ └── Produit.sql
│ ├── Views/
│ │ └── v_ProduitsActifs.sql
│ └── StoredProcedures/
│ └── usp_Produit_Desactiver.sql
├── Profiles/
│ └── Prod.publish.xml
└── Scripts/
├── PreDeployment.sql
└── PostDeployment.sql
-- dbo/Tables/Produit.sql
CREATE TABLE [dbo].[Produit]
(
[Id] INT IDENTITY (1, 1) NOT NULL,
[CategorieId] INT NOT NULL,
[Libelle] NVARCHAR (200) NOT NULL,
[Prix] DECIMAL (10, 2) NOT NULL,
[Actif] BIT NOT NULL CONSTRAINT [DF_Produit_Actif] DEFAULT (1),
CONSTRAINT [PK_Produit] PRIMARY KEY CLUSTERED ([Id]),
CONSTRAINT [FK_Produit_Categorie] FOREIGN KEY ([CategorieId])
REFERENCES [dbo].[Categorie] ([Id])
);
GO
CREATE NONCLUSTERED INDEX [IX_Produit_CategorieId]
ON [dbo].[Produit] ([CategorieId])
WHERE [Actif] = 1;
Pour ajouter une colonne plus tard, on n’écrit pas d’ALTER TABLE : on modifie simplement le CREATE TABLE. C’est SqlPackage qui générera l’ALTER au déploiement.
Le script de post-déploiement
Le post-déploiement est exécuté à chaque publication : il doit donc être idempotent. C’est l’endroit idéal pour les données de référence :
-- Scripts/PostDeployment.sql
-- Données de référence : MERGE pour rester idempotent
MERGE INTO [dbo].[Categorie] AS cible
USING (VALUES
(1, N'Livres'),
(2, N'Musique'),
(3, N'Jeux vidéo')
) AS source ([Id], [Libelle])
ON cible.[Id] = source.[Id]
WHEN MATCHED AND cible.[Libelle] <> source.[Libelle] THEN
UPDATE SET [Libelle] = source.[Libelle]
WHEN NOT MATCHED BY TARGET THEN
INSERT ([Id], [Libelle]) VALUES (source.[Id], source.[Libelle]);
GO
-- Données de démonstration uniquement hors production (variable SQLCMD)
IF '$(Environnement)' <> 'Prod'
BEGIN
PRINT 'Insertion des données de test';
-- :r inclut un autre fichier SQL du projet
:r .\DonneesDeTest.sql
END
Compiler : dotnet build
dotnet build .\Boutique.Database\Boutique.Database.sqlproj -c Release
Le build valide le modèle complet (références entre objets, syntaxe, compatibilité avec la plateforme) et produit le fichier bin/Release/Boutique.Database.dacpac. Une faute dans une vue ou une colonne inexistante dans une procédure stockée est détectée ici, comme une erreur de compilation C# :
Produit.sql(12,5): Build error SQL71501: Procedure: [dbo].[usp_Produit_Desactiver] has an
unresolved reference to object [dbo].[Produit].[EstActif].
SqlPackage : extraire, publier, comparer
SqlPackage est l’outil en ligne de commande qui manipule les DacPac. Il s’installe comme un outil .NET, en global ou en local au dépôt (voir l’article sur l’installation d’outils par projet) :
# Installation globale
dotnet tool install -g Microsoft.SqlPackage
# Ou installation locale, versionnée avec le dépôt
dotnet new tool-manifest
dotnet tool install Microsoft.SqlPackage
Extract : partir d’une base existante
# Extraire le schéma d'une base existante dans un .dacpac
sqlpackage /Action:Extract `
/SourceConnectionString:"Server=localhost;Database=Boutique;Integrated Security=True;TrustServerCertificate=True" `
/TargetFile:.\Boutique.dacpac
# Extraire directement en fichiers .sql (un fichier par objet, rangés par schéma et type)
# pour initialiser un projet SQL à partir d'une base existante
sqlpackage /Action:Extract `
/SourceConnectionString:"Server=localhost;Database=Boutique;Integrated Security=True;TrustServerCertificate=True" `
/TargetFile:.\Boutique.Database `
/p:ExtractTarget=SchemaObjectType
Publish : déployer
sqlpackage /Action:Publish `
/SourceFile:.\bin\Release\Boutique.Database.dacpac `
/TargetConnectionString:"Server=sql-recette;Database=Boutique;User Id=deploy;Password=***;TrustServerCertificate=True" `
/p:BlockOnPossibleDataLoss=True `
/p:DropObjectsNotInSource=False `
/p:BackupDatabaseBeforeChanges=False `
/v:Environnement=Recette
Si la base n’existe pas, elle est créée ; sinon elle est mise à niveau. Le déploiement est idempotent : publier deux fois le même DacPac ne fait rien la seconde fois.
Script et DeployReport : vérifier avant de déployer
En production, on veut généralement voir ce qui va se passer avant de le faire :
# Générer le script SQL de mise à jour, sans l'exécuter
sqlpackage /Action:Script `
/SourceFile:.\bin\Release\Boutique.Database.dacpac `
/TargetConnectionString:"Server=sql-prod;Database=Boutique;..." `
/OutputPath:.\deploy-prod.sql
# Générer un rapport XML des opérations prévues (création, modification, suppression)
sqlpackage /Action:DeployReport `
/SourceFile:.\bin\Release\Boutique.Database.dacpac `
/TargetConnectionString:"Server=sql-prod;Database=Boutique;..." `
/OutputPath:.\deploy-report.xml
Le rapport liste les opérations et les alertes, notamment les risques de perte de données :
<DeploymentReport xmlns="http://schemas.microsoft.com/sqlserver/dac/DeployReport/2012/02">
<Alerts>
<Alert Name="DataIssue">
<Issue Value="The column [dbo].[Produit].[Description] is being dropped, data loss could occur." />
</Alert>
</Alerts>
<Operations>
<Operation Name="Alter">
<Item Value="[dbo].[Produit]" Type="SqlTable" />
</Operation>
<Operation Name="Create">
<Item Value="[dbo].[v_ProduitsActifs]" Type="SqlView" />
</Operation>
</Operations>
</DeploymentReport>
Les options utiles
| Option | Défaut | Effet |
|---|---|---|
BlockOnPossibleDataLoss |
True |
Stoppe le déploiement si une opération peut perdre des données (colonne supprimée, type réduit) |
DropObjectsNotInSource |
False |
Supprime de la cible les objets absents du DacPac |
DoNotDropObjectTypes |
— | Types jamais supprimés, même avec DropObjectsNotInSource (ex : Users;Logins) |
ExcludeObjectTypes |
— | Types ignorés lors de la comparaison (ex : Users;RoleMembership) |
BackupDatabaseBeforeChanges |
False |
Sauvegarde la base avant modification (SQL Server uniquement) |
GenerateSmartDefaults |
False |
Fournit une valeur par défaut pour une nouvelle colonne NOT NULL sur une table non vide |
IncludeTransactionalScripts |
False |
Encapsule le déploiement dans des transactions |
ScriptDatabaseOptions |
True |
Aligne les options de la base (recovery model, compatibilité…) sur le projet |
# ❌ En production : supprime tout ce qui n'est pas dans le projet,
# y compris les utilisateurs créés par le DBA et les tables d'un autre outil
/p:DropObjectsNotInSource=True /p:BlockOnPossibleDataLoss=False
# ✅ Prudent : on bloque toute perte de données et on protège la sécurité
/p:BlockOnPossibleDataLoss=True /p:DropObjectsNotInSource=True `
/p:DoNotDropObjectTypes="Users;Logins;RoleMembership;Permissions"
Le piège du renommage
SqlPackage compare des états : si une colonne Prix devient PrixHT dans le CREATE TABLE, il voit une colonne supprimée et une colonne ajoutée. Résultat : DROP COLUMN, perte de données (ou blocage grâce à BlockOnPossibleDataLoss). Deux solutions :
- utiliser le refactoring « Renommer » de Visual Studio / SSDT, qui enregistre l’intention dans un fichier
.refactorlog; SqlPackage génère alors unsp_rename; - ou effectuer le renommage dans le script de pré-déploiement, de façon idempotente :
-- Scripts/PreDeployment.sql
IF COL_LENGTH('dbo.Produit', 'Prix') IS NOT NULL
AND COL_LENGTH('dbo.Produit', 'PrixHT') IS NULL
BEGIN
EXEC sp_rename 'dbo.Produit.Prix', 'PrixHT', 'COLUMN';
END
Le publish profile
Répéter les options sur chaque ligne de commande devient vite pénible. Un publish profile est un fichier MSBuild qui regroupe les options par environnement :
<?xml version="1.0" encoding="utf-8"?>
<!-- Profiles/Prod.publish.xml -->
<Project ToolsVersion="Current" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<TargetDatabaseName>Boutique</TargetDatabaseName>
<BlockOnPossibleDataLoss>True</BlockOnPossibleDataLoss>
<DropObjectsNotInSource>True</DropObjectsNotInSource>
<DoNotDropObjectTypes>Users;Logins;RoleMembership;Permissions</DoNotDropObjectTypes>
<ExcludeObjectTypes>Users;Logins;RoleMembership;Permissions</ExcludeObjectTypes>
<IncludeTransactionalScripts>True</IncludeTransactionalScripts>
<ScriptDatabaseOptions>False</ScriptDatabaseOptions>
<GenerateSmartDefaults>True</GenerateSmartDefaults>
</PropertyGroup>
<ItemGroup>
<SqlCmdVariable Include="Environnement">
<Value>Prod</Value>
</SqlCmdVariable>
</ItemGroup>
</Project>
La chaîne de connexion, qui contient un secret, reste hors du fichier versionné : on la passe en ligne de commande, et elle s’ajoute aux paramètres du profil.
sqlpackage /Action:Publish `
/SourceFile:.\bin\Release\Boutique.Database.dacpac `
/Profile:.\Profiles\Prod.publish.xml `
/TargetConnectionString:"$env:SQL_CONNECTION_STRING"
Intégration continue avec GitHub Actions
Le workflow de déploiement
graph LR
Dev["Développeur<br/>modifie les .sql"]
Git["Push / Pull Request"]
Build["CI : dotnet build<br/>→ .dacpac"]
Report["DeployReport<br/>+ Script"]
Review["Revue du rapport<br/>(approbation)"]
Recette["Publish<br/>Recette"]
Prod["Publish<br/>Production"]
Dev --> Git --> Build --> Recette
Build --> Report --> Review --> Prod
style Dev fill:#4A90E2
style Build fill:#F5A623
style Report fill:#F5A623
style Review fill:#BD10E0
style Recette fill:#7ED321
style Prod fill:#D0021B
Le DacPac est construit une seule fois puis promu d’environnement en environnement : la base de production reçoit exactement le même artefact que celui testé en recette.
Exemple de pipeline
# .github/workflows/database.yml
name: Base de données
on:
push:
branches: [main]
paths: ['src/Boutique.Database/**']
pull_request:
paths: ['src/Boutique.Database/**']
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
# Valide le schéma : une référence cassée fait échouer la PR
- name: Build du projet SQL
run: dotnet build src/Boutique.Database/Boutique.Database.sqlproj -c Release
- uses: actions/upload-artifact@v4
with:
name: dacpac
path: src/Boutique.Database/bin/Release/Boutique.Database.dacpac
deploy-prod:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment: production # approbation manuelle configurée sur l'environnement
steps:
- uses: actions/checkout@v4 # pour récupérer le publish profile
- uses: actions/setup-dotnet@v4
with:
dotnet-version: '10.0.x'
- uses: actions/download-artifact@v4
with:
name: dacpac
path: artifact
- name: Installer SqlPackage
run: |
dotnet tool install -g Microsoft.SqlPackage
echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
- name: Rapport de déploiement
run: >
sqlpackage /Action:DeployReport
/SourceFile:artifact/Boutique.Database.dacpac
/Profile:src/Boutique.Database/Profiles/Prod.publish.xml
/TargetConnectionString:"${{ secrets.SQL_CONNECTION_STRING }}"
/OutputPath:deploy-report.xml
- uses: actions/upload-artifact@v4
with:
name: deploy-report
path: deploy-report.xml
- name: Publication
run: >
sqlpackage /Action:Publish
/SourceFile:artifact/Boutique.Database.dacpac
/Profile:src/Boutique.Database/Profiles/Prod.publish.xml
/TargetConnectionString:"${{ secrets.SQL_CONNECTION_STRING }}"
Quelques remarques :
- La chaîne de connexion est stockée dans les secrets de l’environnement
production, jamais dans le dépôt. - L’environnement GitHub
productionpeut exiger une approbation manuelle : le déploiement attend qu’un relecteur valide. - Le rapport de déploiement est archivé comme artefact : on garde une trace de ce qui a été appliqué.
- Pour Azure SQL, l’action
azure/sql-actionencapsule le même fonctionnement (build du.sqlprojpuis publish) ; l’appel direct à SqlPackage a l’avantage d’être identique en local et en CI.
Exemple de workflow complet
- Développer le schéma dans un projet SQL (SDK-style avec VS Code ou Visual Studio, ou SSDT classique).
- Compiler le projet pour générer le DacPac à chaque modification (
dotnet build). - Versionner les fichiers
.sqldans le contrôle de source (Git, Azure DevOps, etc.) ; le DacPac, lui, est un artefact de build. - Déployer ou mettre à jour les bases de données cibles via le DacPac, manuellement ou dans un pipeline CI/CD.
- Utiliser
DeployReportetScriptpour valider les différences avant déploiement.
DacPac et SSDT
SQL Server Data Tools (SSDT) est l’environnement de développement intégré dans Visual Studio pour la conception, le développement et la gestion des bases de données SQL Server. SSDT permet de :
- Créer des projets de base de données, gérer le schéma sous forme de code source et générer facilement des fichiers DacPac.
- Modéliser la base de données sous forme de projet, facilitant la gestion du schéma dans un système de contrôle de version.
- Générer un DacPac à partir d’un projet SSDT pour déployer ou mettre à jour des bases de données.
- Comparer des schémas et automatiser le déploiement via DacPac, intégrés à Visual Studio et aux pipelines DevOps.
SSDT reste l’outil historique, avec ses designers et son refactoring. Les projets SDK-style Microsoft.Build.Sql reprennent le même format de modèle et produisent le même DacPac, mais sans dépendre de Visual Studio : c’est ce qui rend l’approche naturelle dans une CI Linux ou sous VS Code.
Résumé
| Étape | Outil / commande |
|---|---|
| Créer le projet | dotnet new sqlproj (SDK Microsoft.Build.Sql) |
| Décrire le schéma | Un fichier CREATE par objet, scripts pre/post-déploiement idempotents |
| Compiler et valider | dotnet build → bin/Release/*.dacpac |
| Partir d’une base existante | sqlpackage /Action:Extract (/p:ExtractTarget=SchemaObjectType pour des fichiers) |
| Vérifier avant de déployer | sqlpackage /Action:DeployReport et /Action:Script |
| Déployer | sqlpackage /Action:Publish avec BlockOnPossibleDataLoss=True |
| Configurer par environnement | Publish profile *.publish.xml + variables SQLCMD (/v:) |
| Automatiser | GitHub Actions : build une fois, approbation, publish |