Manage configurations in SQL Server Database project via SQLCMD variables

What Is Database Project?

The purpose of a Database Project is to create and manage SQL database scripts. It allows us to view quickly, design, modify, and test database objects such as tables, views, queries, and stored procedures without jumping from the Visual Studio environment to a different toolset. Effectively, a database project converts all the objects in your database into text files that can be searched, modified, and stored in source control, just like your code files.   

The main advantage of using a Database project is its design, development, and deployment productivity. It provides schema comparison functionality for deployment between different servers. It also manages the deployment of a project to multiple environments. It can easily track changes made over time with the capability of reverting to the previous version if an error has occurred. It is also an excellent place for documentation of a database which is more effective to view than in extended properties.

Creating A New Database Project

Open Visual Studio and search for SQL Server Database Project.

This image shows the Open Visual Studio and search for SQL Server Database Project

Click next and specify the name for the project. Click on the Create button.

this image shows the specify the name for the project. Click on the Create button.


SQLCMD is a utility used for interactive execution of T-SQL statements, stored procedures, and automating T-SQL scripting tasks. It allows you to use predefined and custom-defined variables. There are various modes available to use this utility. In this article, we are using SQLCMD MODE in the Database project visual studio.

Adding SQLCMD Variable:

To add a SQLCMD variable, right-click on the project and click Properties. In properties, navigate to the SQLCMD Variables tab and define variables here.  

Variables are defined using $(variableName) notation (refer to the screenshot below). We have defined variable name $(Env). This is the name that must be referenced in pre- or post-deployment scripts. You can add as many variables as per your requirement. 

The value in the Default column will get saved in the project file (.sqlproj), and the value in Local column will be specific to your machine and get saved in the .user file. If you have both variables filled in, then the variable Local has higher precedence over the Default for publishing. If only the Default variable is filled in, then no values will be filled in automatically until you click on the Load values button.  

Further Reading: Introduction to Azure Cosmos DB

Transform Your Custom Development with AlphaBOLD

At AlphaBOLD, we believe in innovation and excellence in development services. Whether it's custom software or database management, our experts are ready to help you achieve your business goals.

Request a Consultation
This image shows the Adding SQLCMD Variable

Guidelines For SQLCMD Variable Names:

Consider the following guidelines when defining SQLCMD variable: 

  • Scripting variables are not case sensitive. 
  • They must not contain white space characters or quotation marks. 
  • They must not have the same form as a variable expression such as $(var)

Defining & Setting SQLCMD Variables :

There are two ways to define and set variables.

Using Setvar Command:

The following is the syntax to reference a variable in the post-deployment script.  

 :setvar TableName MyTable  

 SELECT * FROM [$(TableName)] 

Using -V Switch:

We can define variables implicitly by using -v switch of SQLCMD. Variable names must be after-v switch, followed with an equal sign and the value:

sqlcmd -v variable = value 

Including A File In Pre- Or Post-Deployment Script:

The following is the syntax to include a file in the post-deployment script:  

:r .myfile.sql  

Differentiation Between T-SQL And SQLCMD Statements

All statements beginning with a colon in the T-SQL script are SQLCMD statements. This makes the difference between SQLCMD and T-SQL clear.  

To avoid compilation errors in the project, it is important to enable the SQLCMD mode. 

Further Reading: Database Optimization Techniques – Improve Performance Of Your Code

This image shows the T-SQL And SQLCMD Statements

Managing Configurations At Runtime

 SQLCMD variables can be utilized to provide a dynamic substitution for both debugging and publishing. You can use variables and values during build, pre-deployment, or post-deployment. The database objects are created using the assigned values. The following is an example of a post-deployment script that executes different scripts depending upon the value of the variable “DeployType.”

This image shows the Managing Configurations At Runtime

Achieve Excellence with AlphaBOLD's Development Services

AlphaBOLD is dedicated to delivering excellence in every project. Our comprehensive development services are designed to meet your business's specific challenges and opportunities.

Request a Consultation


Database projects, along with SQLCMD utility, make it a powerful application environment where you can develop an entire database and automate the complete development lifecycle. This article was focused on how to create SQLCMD variables and their usage.

Explore Recent Blog Posts

Infographics show the 2021 MSUS Partner Award winner

Related Posts

Receive Updates on Youtube