What SSDT-PM files are and why you need one
An SSDT-PM file (SQL Server Data Tools Project Manifest) is a configuration file that SQL Server Data Tools uses to track project settings, deployment options, and build properties for database projects. If you are working with SQL Server database development in Visual Studio, this file stores information about how your project should build and deploy — things like target SQL Server version, whether to treat warnings as errors, and what pre-deployment or post-deployment scripts to run.
You do not manually create this file from scratch in most cases. Visual Studio generates it automatically when you create a new SQL Server database project. However, if you are setting up a project from existing code, migrating from an older format, or need to configure specific deployment settings, you may need to create or modify one yourself.
The file lives in your project root directory and is named with a .sqlproj extension (the actual manifest data is embedded within it). Understanding how to create and configure it means your team can deploy databases consistently across development, testing, and production environments.
Key Takeaways
- SSDT-PM configuration is usually handled automatically by Visual Studio when you create a new SQL Server database project, so manual creation is rarely necessary.
- If you need to create one manually, you are editing the .sqlproj file itself, which is XML-based and contains build and deployment settings.
- The file specifies your target SQL Server version, deployment options, and whether to include pre- or post-deployment scripts.
- You can edit the .sqlproj file directly in Visual Studio by right-clicking the project, selecting Unload Project, then Edit Project File.
Creating a new SQL Server database project (the normal way)
The easiest path is to let Visual Studio create the SSDT-PM configuration for you. Open Visual Studio, go to File > New > Project, search for "SQL Server Database Project", and select it. Choose your project name and location, then click Create. Visual Studio generates a .sqlproj file with default settings appropriate for your SQL Server version.
Once the project is created, you can view and modify the configuration by right-clicking the project name in Solution Explorer, selecting Properties, and adjusting settings like target platform (SQL Server 2019, 2022, etc.), whether to treat build warnings as errors, and deployment options. These changes are saved back into the .sqlproj file automatically.
This approach is faster and safer than manual file creation because Visual Studio validates the XML structure and ensures all required elements are present.
Manually editing the .sqlproj file
If you need to modify SSDT-PM settings directly or troubleshoot a corrupted file, you can edit the .sqlproj file as XML. Right-click your project in Solution Explorer, select Unload Project, then right-click again and select Edit Project File. The file opens in the XML editor.
Look for the PropertyGroup section near the top of the file. This is where deployment and build settings live. Common properties you might adjust include:
- TargetDatabaseVersion — sets the SQL Server version (SqlServer2019, SqlServer2022, etc.)
- TreatTSqlWarningsAsErrors — set to true to fail the build if T-SQL warnings occur
- BlockOnPossibleDataLoss — set to true to prevent deployment if schema changes might lose data
- DeploymentExtensionConfiguration — specifies pre- and post-deployment script behavior
After editing, save the file, right-click the project again, and select Reload Project. Visual Studio validates the XML and reloads the configuration. If there are syntax errors, Visual Studio will report them and prevent the reload until they are fixed.
Setting target SQL Server version
One of the most important SSDT-PM settings is the target SQL Server version. This determines which T-SQL syntax and features are available during development and which version the project can deploy to. Open the .sqlproj file in the XML editor and locate the TargetDatabaseVersion property.
Common values are SqlServer2016, SqlServer2017, SqlServer2019, and SqlServer2022. If you are deploying to Azure SQL Database, use SqlAzure. Setting this correctly prevents you from using syntax that your target server does not support — for example, if you set the target to SQL Server 2016 but use a 2019-only feature, the build will fail with an error.
You can also change this through the Visual Studio UI: right-click the project, select Properties, and look for the Target Platform dropdown. Both methods update the same setting in the .sqlproj file.
Configuring deployment and build options
The .sqlproj file controls how your database project builds and deploys. Key settings include whether to compare schemas before deployment, whether to block deployment if data loss is possible, and how to handle pre- and post-deployment scripts.
Pre-deployment scripts run before schema changes are applied — typically used to back up data or disable constraints. Post-deployment scripts run after schema changes — typically used to populate reference data or re-enable constraints. You specify these in the PropertyGroup section of the .sqlproj file using the PreDeploymentScript and PostDeploymentScript properties, which point to .sql files in your project.
If you are working in a team, these settings should be consistent across all developers' machines. Committing the .sqlproj file to version control (Git, Azure DevOps, etc.) ensures everyone uses the same build and deployment rules.
Troubleshooting common SSDT-PM issues
If your project fails to load or shows build errors related to the .sqlproj file, the XML structure is likely corrupted. Open the file in the XML editor and check for mismatched tags, missing closing brackets, or invalid property values. Visual Studio highlights syntax errors in red.
If you accidentally delete or severely damage the .sqlproj file, the simplest fix is to create a new SQL Server database project, copy your .sql files into it, and let Visual Studio regenerate the configuration. You can then adjust the settings to match your original project.
If builds succeed locally but fail in your CI/CD pipeline, the target SQL Server version or deployment options in the .sqlproj file may not match your pipeline environment. Compare the TargetDatabaseVersion and deployment properties between your local file and the one in your repository.
Frequently Asked Questions
Do I have to create an SSDT-PM file manually?
No. Visual Studio creates it automatically when you create a new SQL Server database project. Manual creation is only necessary if you are migrating legacy code, recovering from file corruption, or setting up a project from scratch without using the Visual Studio template.
What happens if I delete the .sqlproj file?
Your project will no longer load in Visual Studio. The simplest recovery is to create a new SQL Server database project, copy your .sql files into it, and commit the new .sqlproj file to version control. Do not delete this file unless you are intentionally removing the project.
Can I share the same .sqlproj file across multiple projects?
No. Each SQL Server database project needs its own .sqlproj file. If you have multiple related databases, each gets its own project and its own .sqlproj file, though they can share the same solution.
What is the difference between .sqlproj and SSDT-PM?
SSDT-PM is the configuration standard; .sqlproj is the file format that stores it. The terms are often used interchangeably, but .sqlproj is the actual file you work with in Visual Studio.
Can I edit the .sqlproj file while the project is loaded?
No. You must unload the project first (right-click > Unload Project), edit the file, save it, then reload the project. Editing while loaded can cause Visual Studio to overwrite your changes or fail to recognize them.