Skip to content

Commit 0a8de28

Browse files
JamesJBarnettJamesJBarnett
authored
Merge pull request #36490 from dzsquared/drskwier/sqlproj-automation
Add SQL projects automation overview documentation
2 parents d33f6dc + 53928a1 commit 0a8de28

2 files changed

Lines changed: 207 additions & 0 deletions

File tree

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8685,6 +8685,8 @@ items:
86858685
href: tools/sql-database-projects/get-started.md
86868686
- name: SQL projects tools
86878687
href: tools/sql-database-projects/sql-projects-tools.md
8688+
- name: SQL projects automation
8689+
href: tools/sql-database-projects/sql-projects-automation.md
86888690
- name: Tutorials
86898691
items:
86908692
- name: Creating and deploying a SQL project

‎docs/tools/sql-database-projects/sql-projects-automation.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
---
2+
title: "SQL Projects Automation"
3+
description: "This overview reviews setting up automation with SQL database projects for CI/CD pipelines using GitHub Actions, Azure DevOps, and other platforms."
4+
author: dzsquared
5+
ms.author: drskwier
6+
ms.reviewer: randolphwest
7+
ms.date: 01/29/2026
8+
ms.service: sql
9+
ms.subservice: sql-database-projects
10+
ms.topic: overview
11+
ms.collection:
12+
- data-tools
13+
ai-usage: ai-assisted
14+
---
15+
16+
# SQL projects automation
17+
18+
[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance](../../includes/applies-to-version/sql-asdb-asdbmi.md)]
19+
20+
This article provides an overview of automation options for SQL projects across different software delivery platforms. Use automation to integrate SQL database projects into CI/CD pipelines, and deploy database changes consistently and repeatedly.
21+
22+
## What to automate
23+
24+
SQL projects automation typically involves two key tasks in a CI/CD pipeline:
25+
26+
- **Build the SQL project**: Validate the project and produce the deployment artifact (`.dacpac`) by running `dotnet build` on the SQL database project to compile. Optionally, execute [code analysis](concepts/sql-code-analysis/sql-code-analysis.md) rules to check code quality during project build.
27+
28+
- **Deploy the `.dacpac`**: Publish the `.dacpac` to a target database using SqlPackage or a platform-specific task. Deployment can target Azure SQL Database, Azure SQL Managed Instance, SQL Server, or SQL database in Fabric.
29+
30+
:::image type="content" source="media/sql-database-projects/build-deploy.png" alt-text="Diagram showing the flow from SQL project build to dacpac artifact and deployment to a database." lightbox="media/sql-database-projects/build-deploy.png":::
31+
32+
When you integrate these steps into your CI/CD pipeline, database changes are validated on every commit and deployed consistently across environments.
33+
34+
### Common concepts
35+
36+
**Artifact flow**: A typical pipeline separates the build and deploy stages. The build stage compiles the SQL project and produces a `.dacpac` file, which is then published as a pipeline artifact. In a subsequent deploy job (potentially after manual approval), the artifact is downloaded and deployed to the target database. This separation allows you to build once and deploy the same artifact to multiple environments, ensuring consistency.
37+
38+
**Publish or script**: Before deploying to sensitive environments, you can review the deployment plan. SqlPackage supports a `Script` action that generates the T-SQL script that would be executed during deployment, without applying changes. The provided T-SQL script allows database administrators or reviewers to examine the exact changes necessary to apply the `.dacpac` before approval. Similarly, the `DeployReport` action produces an XML report of the planned changes.
39+
40+
**Environment approvals and gates**: Production deployments typically require approval workflows to prevent unintended changes. Both GitHub Actions and Azure DevOps support environment-based approvals. In GitHub, you can configure [environments](https://docs.github.com/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments) with required reviewers and wait timers. In Azure DevOps, [environments](/azure/devops/pipelines/process/environments) support approval gates, business hours restrictions, and other deployment controls. These controls help ensure that database changes are reviewed and approved before reaching production.
41+
42+
### Prerequisites
43+
44+
SqlPackage is cross-platform and runs on Windows, Linux, and macOS. Install it as a .NET global tool to ensure consistent behavior across environments.
45+
46+
- [.NET SDK](https://dotnet.microsoft.com/download) installed on the build agent.
47+
48+
- [SqlPackage](../sqlpackage/sqlpackage.md) installed on the build agent. You can install SqlPackage as a .NET global tool:
49+
50+
```bash
51+
dotnet tool install --global microsoft.sqlpackage
52+
```
53+
54+
## Software delivery platforms
55+
56+
Choose an environment that matches your team's tooling, compliance, and connectivity requirements.
57+
58+
### Managed virtual environments
59+
60+
Microsoft-managed virtual environments for GitHub Actions hosted runners and Azure Pipelines agents include preinstalled tools:
61+
62+
| Environment | .NET SDK | SqlPackage |
63+
| --- | --- | --- |
64+
| **Windows** | Preinstalled | Preinstalled |
65+
| **Linux** | Preinstalled | Not preinstalled |
66+
| **macOS** | Preinstalled | Not preinstalled |
67+
68+
On Linux and macOS environments, install SqlPackage as part of your workflow. For more information on SqlPackage installation and versioning in pipelines, see [SqlPackage in development pipelines](../sqlpackage/sqlpackage-pipelines.md).
69+
70+
### Self-hosted environments
71+
72+
Deploy from a self-hosted runner or agent when you need more control over the environment, such as:
73+
74+
- Network isolation requirements (accessing databases not exposed to the public internet)
75+
- Custom tooling or specific SqlPackage versions
76+
- Compliance or security policies
77+
78+
You can deploy self-hosted runners as [Azure Container Apps jobs](/azure/container-apps/tutorial-ci-cd-runners-jobs) for event-driven, serverless execution. Use this approach to define the environment in a Dockerfile and install SqlPackage and other tools as needed.
79+
80+
## GitHub Actions
81+
82+
The [Azure SQL Deploy action](https://github.com/azure/sql-action) (`azure/sql-action`) provides an integrated experience for deploying SQL projects and `.dacpac` files to Azure SQL and SQL Server from any GitHub Actions runner.
83+
84+
Key capabilities:
85+
86+
- Deploys `.dacpac`, `.sqlproj`, or `.sql` scripts.
87+
- Supports SQL authentication, Microsoft Entra ID authentication, and service principal authentication.
88+
- Automatically adds and removes temporary firewall rules for Azure SQL Database when combined with `azure/login`.
89+
- Works on both Windows and Linux runners.
90+
91+
### Example: Deploy a SQL project with GitHub Actions
92+
93+
```yaml
94+
# .github/workflows/sql-deploy.yml
95+
on: [push]
96+
97+
jobs:
98+
build-and-deploy:
99+
runs-on: ubuntu-latest
100+
steps:
101+
- uses: actions/checkout@v4
102+
103+
- uses: azure/sql-action@v2
104+
with:
105+
connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
106+
path: './Database.sqlproj'
107+
action: 'publish'
108+
```
109+
110+
For Azure SQL Database deployments that require a temporary firewall rule, add the `azure/login` step before `sql-action`:
111+
112+
```yaml
113+
- uses: azure/login@v2
114+
with:
115+
creds: ${{ secrets.AZURE_CREDENTIALS }}
116+
117+
- uses: azure/sql-action@v2
118+
with:
119+
connection-string: ${{ secrets.AZURE_SQL_CONNECTION_STRING }}
120+
path: './Database.dacpac'
121+
action: 'publish'
122+
```
123+
124+
You can also use SqlPackage directly on any runner. For more information, see [SqlPackage in development pipelines](../sqlpackage/sqlpackage-pipelines.md).
125+
126+
## Azure Pipelines
127+
128+
Azure DevOps provides the [SqlAzureDacpacDeployment](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1) task for deploying `.dacpac` files and SQL scripts to Azure SQL Database.
129+
130+
Key capabilities:
131+
132+
- Deploys `.dacpac` files or executes SQL scripts.
133+
- Supports SQL authentication, Microsoft Entra ID authentication, and service principal authentication.
134+
- Automatically manages firewall rules for Azure SQL Database.
135+
- Requires a Windows agent (use SqlPackage directly on Linux agents).
136+
137+
### Example: Deploy a `.dacpac` with Azure DevOps
138+
139+
```yaml
140+
# azure-pipelines.yml
141+
trigger:
142+
- main
143+
144+
pool:
145+
vmImage: 'windows-latest'
146+
147+
steps:
148+
- task: SqlAzureDacpacDeployment@1
149+
inputs:
150+
azureSubscription: 'your-service-connection'
151+
AuthenticationType: 'server'
152+
ServerName: 'your-server.database.windows.net'
153+
DatabaseName: 'your-database'
154+
SqlUsername: '$(SqlUser)'
155+
SqlPassword: '$(SqlPassword)'
156+
deployType: 'DacpacTask'
157+
DeploymentAction: 'Publish'
158+
DacpacFile: '$(Build.ArtifactStagingDirectory)/Database.dacpac'
159+
```
160+
161+
For Linux agents or more control over the deployment process, use SqlPackage directly:
162+
163+
```yaml
164+
steps:
165+
- task: UseDotNet@2
166+
inputs:
167+
packageType: 'sdk'
168+
version: '8.x'
169+
170+
- script: dotnet tool install --global microsoft.sqlpackage
171+
displayName: 'Install SqlPackage'
172+
173+
- script: |
174+
sqlpackage /Action:Publish \
175+
/SourceFile:$(Build.ArtifactStagingDirectory)/Database.dacpac \
176+
/TargetConnectionString:"$(ConnectionString)"
177+
displayName: 'Deploy database'
178+
```
179+
180+
## Other CI/CD platforms
181+
182+
For platforms such as GitLab CI/CD, Jenkins, CircleCI, or others, use SqlPackage directly to build and deploy SQL projects.
183+
184+
### Build the project
185+
186+
```bash
187+
dotnet build ./Database.sqlproj -c Release
188+
```
189+
190+
### Deploy the `.dacpac`
191+
192+
```bash
193+
sqlpackage /Action:Publish \
194+
/SourceFile:./bin/Release/Database.dacpac \
195+
/TargetConnectionString:"Server=your-server;Database=your-db;User Id=user;Password=password;"
196+
```
197+
198+
## Related content
199+
200+
- [Tutorial: Create and deploy a SQL project](tutorials/create-deploy-sql-project.md)
201+
- [SqlPackage in development pipelines](../sqlpackage/sqlpackage-pipelines.md)
202+
- [SQL projects tools](sql-projects-tools.md)
203+
- [SqlPackage overview](../sqlpackage/sqlpackage.md)
204+
- [Azure SQL Deploy action (GitHub)](https://github.com/azure/sql-action)
205+
- [SqlAzureDacpacDeployment task reference](/azure/devops/pipelines/tasks/reference/sql-azure-dacpac-deployment-v1)

0 commit comments

Comments
 (0)