Skip to content

Commit 0c3e409

Browse files
dzsquareddzsquared
authored
Add publish profile documentation for SQL projects (#37036)
Add concept article explaining what publish profiles are, their file format, deployment options, SQLCMD variables, and tool support. Includes how to create a publish profile during deployment, load it for future use, and use it with SqlPackage CLI. Update TOC.
1 parent 31937fe commit 0c3e409

2 files changed

Lines changed: 160 additions & 0 deletions

File tree

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8725,6 +8725,8 @@ items:
87258725
href: tools/sql-database-projects/concepts/schema-comparison.md
87268726
- name: SQLCMD variables
87278727
href: tools/sql-database-projects/concepts/sqlcmd-variables.md
8728+
- name: Publish profiles
8729+
href: tools/sql-database-projects/concepts/publish-profiles.md
87288730
- name: System objects
87298731
href: tools/sql-database-projects/concepts/system-objects.md
87308732
- name: Target platform

‎docs/tools/sql-database-projects/concepts/publish-profiles.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Publish Profiles Overview
3+
description: Learn about publish profiles for SQL projects, including the deployment settings, SQLCMD variables, and connection information they store.
4+
author: dzsquared
5+
ms.author: drskwier
6+
ms.reviewer: randolphwest
7+
ms.date: 04/10/2026
8+
ms.service: sql
9+
ms.subservice: sql-database-projects
10+
ms.topic: concept-article
11+
ms.collection:
12+
- data-tools
13+
zone_pivot_groups: sq1-sql-projects-tools
14+
---
15+
16+
# Publish profiles overview
17+
18+
[!INCLUDE [SQL Server Azure SQL Database Azure SQL Managed Instance FabricSQLDB](../../../includes/applies-to-version/sql-asdb-asdbmi-fabricsqldb.md)]
19+
20+
A publish profile is a file that stores deployment configuration for a SQL project. Publish profiles can encapsulate target connection information, deployment options, and SQLCMD variable values in a reusable `.publish.xml` file. Publish profiles are especially useful when your deployment requires specific settings, like excluding certain object types or ignoring target platform differences. Instead of specifying these options each time you deploy, save them in a publish profile and reuse it.
21+
22+
When working with SQL projects, you can create and store multiple publish profiles. During deployment, select a publish profile to apply consistent settings without manually selecting multiple options.
23+
24+
## Publish profile file format
25+
26+
A publish profile is an XML file with the `.publish.xml` extension. The file contains properties and items that define deployment behavior in the XML path `/Project/PropertyGroup`.
27+
28+
A publish profile can include the following information:
29+
30+
- **Target connection string** - the connection string for the target database server
31+
- **Target database name** - the name of the database to deploy to
32+
- **Deployment options** - settings that control deployment behavior, such as whether to drop objects not in the source or block on possible data loss
33+
- **SQLCMD variable values** - values for SQLCMD variables defined in the SQL project, applied at deployment time
34+
35+
### Sample publish profile
36+
37+
The following example shows a publish profile that targets a local SQL Server instance. It sets two deployment options and provides a value for one SQLCMD variable:
38+
39+
```xml
40+
<?xml version="1.0" encoding="utf-8"?>
41+
<Project >
42+
<PropertyGroup>
43+
<IncludeCompositeObjects>True</IncludeCompositeObjects>
44+
<TargetDatabaseName>AdventureWorks</TargetDatabaseName>
45+
<AllowIncompatiblePlatform>True</AllowIncompatiblePlatform>
46+
<ProfileVersionNumber>1</ProfileVersionNumber>
47+
</PropertyGroup>
48+
<ItemGroup>
49+
<SqlCmdVariable Include="EnvironmentName">
50+
<Value>staging</Value>
51+
</SqlCmdVariable>
52+
</ItemGroup>
53+
</Project>
54+
```
55+
56+
### Publish profile entry in project file
57+
58+
When you add a publish profile to a SQL project, it adds an entry to the project file (`.sqlproj`) that includes the path to the publish profile file:
59+
60+
```xml
61+
<ItemGroup>
62+
<None Include="Staging.publish.xml" />
63+
</ItemGroup>
64+
```
65+
66+
While you can specify any publish profile using the `/Profile:` parameter with SqlPackage, publish profiles included in the project file appear in the solution explorer or database projects view of your SQL project tool. This feature makes them easier to manage and select during deployment.
67+
68+
## Deployment options in publish profiles
69+
70+
Deployment options control the behavior of the deployment engine when applying changes to a target database. These options correspond to the properties available in the [SqlPackage Publish](../../sqlpackage/sqlpackage-publish.md) action and the `DacDeployOptions` class in the DacFx API.
71+
72+
Commonly used deployment options include:
73+
74+
| Option | Default | Description |
75+
| --- | --- | --- |
76+
| `AllowIncompatiblePlatform` | `False` | Attempts deployment even if there are platform compatibility differences. |
77+
| `BlockOnPossibleDataLoss` | `True` | Stops deployment if a change could result in data loss. |
78+
| `DropObjectsNotInSource` | `False` | Drops objects in the target database that don't exist in the source project. |
79+
| `IgnoreColumnOrder` | `False` | Ignores differences in column order between source and target. |
80+
| `ScriptDatabaseOptions` | `True` | Scripts database-level options such as compatibility level during deployment. |
81+
82+
For a complete list of deployment options and their default values, see [SqlPackage Publish properties](../../sqlpackage/sqlpackage-publish.md#properties-specific-to-the-publish-action).
83+
84+
## SQLCMD variables in publish profiles
85+
86+
[SQLCMD variables](sqlcmd-variables.md) defined in a SQL project can have their values set in a publish profile. When the publish profile is used for deployment, the SQLCMD variable values from the profile override any default values in the project.
87+
88+
The publish profile stores SQLCMD variables as `<SqlCmdVariable>` items:
89+
90+
```xml
91+
<ItemGroup>
92+
<SqlCmdVariable Include="EnvironmentName">
93+
<Value>staging</Value>
94+
</SqlCmdVariable>
95+
<SqlCmdVariable Include="FirstHistoricalYear">
96+
<Value>2005</Value>
97+
</SqlCmdVariable>
98+
</ItemGroup>
99+
```
100+
101+
Values specified on the command line with `/v:` override both the project default and publish profile values.
102+
103+
## Use publish profiles with tools
104+
105+
Publish profiles are supported across SQL project tools and the SqlPackage command-line interface.
106+
107+
::: zone pivot="sq1-visual-studio"
108+
109+
In Visual Studio (SSDT), create and load publish profiles from the **Publish** dialog. When you configure deployment settings and select **Save Profile As**, the settings are saved to a `.publish.xml` file. You can load a previously saved profile by selecting **Load Profile** in the **Publish** dialog. Publish profiles are stored as items in the SQL project and appear in **Solution Explorer**.
110+
111+
Add new publish profiles to the project with the **Add New Item** dialog, and selecting the **Publish Profile** item template. Add existing publish profile files to the project using **Add > Existing Item**.
112+
113+
When you double-click a publish profile from **Solution Explorer**, it opens the **Publish** dialog with the settings from the profile applied. You can review or modify these settings before deployment.
114+
115+
::: zone-end
116+
117+
::: zone pivot="sq1-visual-studio-sdk"
118+
119+
In SDK-style SQL projects in Visual Studio, create and load publish profiles from the **Publish** dialog. When you configure deployment settings and select **Save Profile As**, the settings are saved to a `.publish.xml` file. You can load a previously saved profile by selecting **Load Profile** in the **Publish** dialog.
120+
121+
::: zone-end
122+
123+
::: zone pivot="sq1-visual-studio-code"
124+
125+
In Visual Studio Code with the SQL Database Projects extension, create publish profiles from the **Publish** dialog using the **Save As** option. The publish profile is saved as a `.publish.xml` file that you can add to the project. You can load a previously saved profile by selecting it from **Select Profile** in the **Publish** dialog.
126+
127+
Add new publish profiles to the project by selecting the **Add Publish Profile** option from the project context menu. Add existing publish profile files to the project with **Add Existing Item...**.
128+
129+
In Visual Studio Code with the SQL Database Projects extension, publish profiles appear under the project node in the **Database Projects** view. When you publish a project, you can select an existing publish profile or proceed without one.
130+
131+
::: zone-end
132+
133+
::: zone pivot="sq1-sql-server-management-studio"
134+
135+
In SQL Server Management Studio (SSMS), create and load publish profiles from the **Publish** dialog. When you configure deployment settings and select **Save Profile As**, the settings are saved to a `.publish.xml` file. You can load a previously saved profile by selecting **Load Profile** in the **Publish** dialog. Publish profiles are stored as items in the SQL project and appear in **Solution Explorer**.
136+
137+
Add new publish profiles to the project with the **Add New Item** dialog, and selecting the **Publish Profile** item template. Add existing publish profile files to the project using **Add > Existing Item**.
138+
139+
::: zone-end
140+
141+
::: zone pivot="sq1-command-line"
142+
143+
With the SqlPackage command-line interface, specify a publish profile with the `/Profile:` (or `/pr:`) parameter:
144+
145+
```bash
146+
sqlpackage /Action:Publish /SourceFile:AdventureWorks.dacpac /Profile:production.publish.xml
147+
```
148+
149+
Properties and SQLCMD variable values that you specify on the command line override values in the publish profile. For more information, see [SqlPackage Publish](../../sqlpackage/sqlpackage-publish.md).
150+
151+
::: zone-end
152+
153+
## Related content
154+
155+
- [SQLCMD variables overview](sqlcmd-variables.md)
156+
- [SqlPackage Publish parameters, properties, and SQLCMD variables](../../sqlpackage/sqlpackage-publish.md)
157+
- [SQL projects properties](project-properties.md)
158+
- [Tutorial: Create and deploy a SQL project](../tutorials/create-deploy-sql-project.md)

0 commit comments

Comments
 (0)