https://docs.sqldsc.com/Recent content in SQL Server Desired State Configuration on SQLDSC DocumentationHugo -- gohugo.ioen-ushttps://docs.sqldsc.com/docs/whats-new/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/whats-new/What’s New # Starting in 1.31, the application can update itself by running sqldsc update. 1.48 (7 September 2026) # FIX: For SQL Server Agent Jobs, don’t compare the database unless it is a TSQL step The binary is now digitally signed 1.46 (17 May 2026) # PRO: Contained Availability Groups are now supported using the ag_apply_mode attribute The sql_script block now uses -C to trust the server certificate and eliminate errors related to encrypted connections 1.https://docs.sqldsc.com/docs/installation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/installation/Installation # SQLDSC is designed to be used with Visual Studio Code. It provides a great file editor and log file viewer. Install Visual Studio Code # Install Visual Studio Code. By default, it installs for the current user which is usually what you want. Install SQLDSC # Download the lastest version from scaleSQL.com and extract the contents of the ZIP file. The application is a command-line executable. Initialize the repository # In VSCode, open up the directory where sqldsc.https://docs.sqldsc.com/docs/basic-usage/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/basic-usage/Basic Usage # Edit targets.hcl # These are the servers we’ll be testing and applying configuration to. targets.hcl should already look like this: target "localhost" {} /* target "computer_name" {} target "computer\instance" {} target "fqdn.domain.tld" {} */ This will use locahost for testing. The commented out targets are samples to connect to named instances and a fully.qualfied.server.tld. For each targt, sqldsc will try to connect to the name inside the quotes.https://docs.sqldsc.com/docs/getting-started/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/getting-started/Getting Started # This page walks through a process to build a good defaults.hcl file. Baseline # The bare minimum change I make to every SQL Server are for security and fixing up the model database. The sa login should be disabled by default xp_cmdshell is disabled by default and should stay that way. It provides a mechanism to get from SQL Server out to the operating system. The model database should be in SIMPLE recovery.https://docs.sqldsc.com/docs/targets/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/targets/Targets # A sample targets.hcl looks like this: target "D40\SQL2014" {} target "server.domain.com" {} The text in quotes is what it will try to connect to. The full layout of a targets file might look like this: target_defaults { dial_timeout = 10 connect_timeout = 15 } target "my-target" { fqdn = "host:port" dial_timeout = 90 } The target_defaults block sets the defaults for all targets. The dial_timeout is the timeout to resolve the name and talk to the port.https://docs.sqldsc.com/docs/resource-blocks/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/resource-blocks/Resource Blocks # Everything you can set is defined as a Resource Block. Resource blocks have the following format. resource "resource_type" "resource_name" { ensure = "present" ... other key = value entries ... } For resources that are identified using a single string (Logins, Agent Operators, Databases, etc.), the resource_name is often used to identify the resource. It can be overridden using the appropriate attribute. Please see the Resource Block Schema section.https://docs.sqldsc.com/docs/schema/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/schema/Resource Block Schema # Each resource block MAY have an ensure attribute. The possible values are: present - If the resource doesn’t exist, create it. If it exists, alter it to match the resource block. absent - If the resource exists, remove it alter - If the resource exists, alter it. If it doesn’t exist, do nothing. If no ensure attribute is found, it defaults to present Server Resource Blocks # The following resource block types are supportedhttps://docs.sqldsc.com/docs/file-layout/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/file-layout/File Layout # By default, the configuration files are stored in the config directory. config\ nodes\ ServerA.hcl ServerA__instance1.hcl serverB.hcl ServerB\ defaults.hcl Instance1.hcl Instance2.hcl defaults.hcl targets.hcl targets.hcl lists the targets that will be configured The configurations in defaults.hcl will be applied to all targets. The configurations stored in nodes\ServerA.hcl will override the defaults for all instances on ServerA. AND they will be applied to the default instance on ServerA. Configuring Named Instances # Prior to 1.https://docs.sqldsc.com/docs/precedence/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/precedence/Resource Block Precedence # A given resource can be defined in multiple places. The resources will be merged together to create the final configuration for the resource. Each of these files can define the same configuration. For example, to configure the txn instance on node2 in this example, the following files would be used. Each lower file overrides the values in the higher file. The more specific file overrides the more general file.https://docs.sqldsc.com/docs/sql-server-logins/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/sql-server-logins/Managing SQL Server Logins # This section only applies to SQL Server logins. It doesn’t apply to domain users, domain groups, certificate-based logins, etc. SQLDSC provides multiple mechanisms to make managing SQL Server logins simpler. These are focused on the SID and the password (hash). SQL Server matches SQL Server logins to database users using the SID and not the name. A SID is a binary string whose hex representation looks like this: 0x79C4A6315F6A1942AAD4A386D816BAAC.https://docs.sqldsc.com/docs/linked-servers/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/linked-servers/Linked Servers (BETA) # Linked Server support was added in 1.43.16. It supports the linked_server and linked_login Resource Blocks. Resource Block Schema # linked_server - Some settings cannot be changed on existing servers. All values are optional. name (string - optional. If not provided, it defaults to the resource name) product (string) provider (string) data_source (string) catalog|database (string) You can use either catalog or database for this field. data_access (boolean) This can be altered connect_timeout (int) This can be altered query_timeout (int) This can be altered rpc (boolean) Enables RPC from the remote server and can be altered rpc_out (boolean) Enables RPC to the remote server and can be altered msdtc (boolean) This maps remote proc transaction promotion and can be altered.https://docs.sqldsc.com/docs/sp_configure/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/sp_configure/sp_configure Settings # The application can set two configurations for you automatically. # -1 sets a value based on each server's memory # Please see the documentation resource "configuration" "max_memory" { name = "max server memory (MB)" value = -1 ensure = "alter" } # -1 sets a value based on each server's core count # Please see the documentation resource "configuration" "maxdop" { name = "max degree of parallelism" value = -1 ensure = "alter" } Maximum Memory # By default, SQL Server will request all the memory it thinks it needs.https://docs.sqldsc.com/docs/azure/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/azure/Azure # SQLDSC provides limited support for Azure’s various SQL Server offerings. SQL Server installed on Virtual Machines - This should work normally. Managed Instances - This is untested. SQL Database # SQLDSC can connect to an Azure SQL Database by setting the database in the target and creating a SQLDSC credential for the user name and password. target "your-server.database.windows.net" { sqldsc_credential = "azure_credential" database = "your_database" } The following resources have been tested against Azure SQL Databases:https://docs.sqldsc.com/docs/permissions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/permissions/Permissions # The application itself doesn’t need any special permissions for itself. It does require the user running to be in the sysadmin role. If you connect using a SQL Server login, that login needs to be in the sysadmin role. If you connect to a target and aren’t in the sysadmin role, the target is skipped. Multiple Accounts # If you use multiple accounts, with different permissions on different instances, consider the following scenarios:https://docs.sqldsc.com/docs/command-line/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/command-line/Command Line # Running sqldsc help will bring up the current command line options. Running sqldsc help command_name will bring up help for a particular command. Common commands include: init - creates directories and sample files test - see what changes it would make apply - make changes to the targets version - display the version information vault - controls stored logins and passwords. See Credential Vault. update - checks for updates and allows you to apply them list - lists targets and their tags after applying any filters (starting in 1.https://docs.sqldsc.com/docs/app-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/app-settings/Application Settings # Certain settings can be configured via a settings file so they are always applied. These settings are: parallel threads http_proxy The following files are searched for in order. If a file is found, it doesn’t search further for files. Command-line flags override settings in this file. %LOCALAPPDATA%\sqldsc\sqldsc.settings.hcl %HOMEDIR%\sqldsc.settings.hcl .\sqldsc.settings.hcl Using the --debug flag will tell you which configuration file is used. A typical settings file might look like this:https://docs.sqldsc.com/docs/vault/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/vault/Credential Vault # SQLSDC provides a simple vault to store credentials (passwords). It operates in one of two modes: Local mode or Repository mode. The most common use case is creating identical logins across multiple servers with the same password. Examples include monitoring tools that require SQL Server logins or Availability Groups that need identical logins. In the login resource, you can specify the sqldsc_credential and it will use the password from that credential for the login.https://docs.sqldsc.com/docs/logging/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/logging/Application Logging # SQLDSC writes a log file of every change it makes. A typical directory structure with log files looks like this: ├───config │ ├───nodes │ ├───tags │ ├───scripts │ └───state └───logs └───2020 └───sqldsc_2020_06_domain_user.ndjson It generates one file per month per user. The file name is sqldsc_YYYYY_MM_domain_user.ndjson. This simplifies keeping log files in a source code repository. The log files are formatted as NDJSON (Newline Delimited JSON). NDJSON means each file holds multiple JSON objects delimited by newline.https://docs.sqldsc.com/docs/repository/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/repository/Using SQLDSC in a Repository # SQLDSC is designed to be used in a GIT repository by multiple users across multiple domains. Consider a sample directory tree. Many of these folders are created by sqldsc init. │ .gitignore │ key.txt │ README.md │ sqldsc.exe │ ├───.vscode │ extensions.json │ settings.json │ ├───config │ │ PROD.defaults.hcl │ │ PROD.targets.hcl │ │ defaults.hcl │ │ OFFICE.defaults.hcl │ │ OFFICE.targets.hcl │ │ │ ├───nodes │ │ ├───PROD │ │ │ USKC-MON01P.https://docs.sqldsc.com/docs/reporting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/reporting/Reporting # The application contains a few simple reports Usage # sqldsc report usage provides a simple report of how many changes SQLDSC has made First Change: 2020-06-24T08:30:57 -05:00 Total Instances: 9 Total Changes: 1,202 Last Change: 2022-10-08T09:00:49 -05:00 Domain: OFFICE Changes: 1,192 Domain: PROD Changes: 10 Servers # sqldsc report servers provides a simple list of servers a summary of changes. The goal of this report is to help identify servers that could be retired.https://docs.sqldsc.com/docs/proxy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/proxy/Proxy Server Support # The PRO Edition needs to communicate with the application portal to validate licenses. It often needs to do this from inside restricted networks. A proxy server can be configured in a number of different ways. Setting the HTTPS_PROXY (or HTTP_PROXY) environment variable before the application is started Setting the http_proxy property in the application setting file Using --http_proxy on the command-line Proxy Use # The proxy is used for the following actionshttps://docs.sqldsc.com/docs/privacy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/privacy/Privacy # This section documents what information is required and uploaded to use the application. PRO Edition: See below Standard Editon: No information is required or usage sent back. There are plans to send raw telemtry information from the Standard Edition. Required Information # To create an account and license on the portal requires: A valid email address An optional company name Uploaded Data # Today # The Free Edition does not upload data.https://docs.sqldsc.com/docs/pro-features/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-features/ PRO Edition: Features # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Features # The Professional Edition supports a number of additional features: Multi-threaded – Run tests in parallel Multiple domains – Easily support multiple domains Tags – Assign multiple servers to tags and set configuration for each tag Filtering – Limit Test and Apply to tags, targets, and/or domains Version-based filtering – Resources (such as scripts) only run against certain versions Variables – Targets and tags can override values in Resource Blocks User Database Blocks – Apply resources across multiple databases on a server Login Blocks – Assign permissions to logins in a single block SQL Script Blocks – Run SQL scripts against targets Queries – Run queries against multiple servers SQL Server Agent Jobs – Create and update SQL Server Agent jobshttps://docs.sqldsc.com/docs/pro-licensing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-licensing/PRO Edition: Licensing # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Purchasing Licenses # Today, the Professional edition requires each tested SQL Server instance to have a one-time purchase of a license through the Portal. The Professional Edition requires one license per server configured. Licenses aren’t assigned to specific computers. As servers are retired, that license can move to a new server.https://docs.sqldsc.com/docs/pro-ag/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-ag/PRO: Availability Groups # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Handling Availability Groups # SQLDSC supports Availability Groups in a number of way. For normal (non-contained) Availability Groups Only put the individual nodes in as targets – not the Listener Put all those nodes in a tag named for the Availability Group Use that tag for the AG settings.https://docs.sqldsc.com/docs/pro-domains/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-domains/PRO: Domains # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Handling Domains # SQLDSC supports configuring machines in diffrent domains. This is done by filtering machines based on domain and assiging different defaults based on the domain. These are handled very differently. Pleaes read carefully. Domain Targets # The PRO version can use domain specific target files.https://docs.sqldsc.com/docs/pro-tags/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-tags/PRO: Tags # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Tags # Each target can be assigned multiple tags. Instances in tags can be given identical configuration. Good uses of tags include: Identical configuration of an AG Separate DEV from PROD Group servers together for processing Group servers in different data centers together Targets # A targets.https://docs.sqldsc.com/docs/pro-logins/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-logins/PRO: Login Blocks # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Starting in 1.37, login blocks provide a simple way for the PRO Edition to configure permissions for a login. A sample looks like this: login "PROD\read-only" { permissions = ["view server state"] user_databases { roles = ["db_datareader"] } database "msdb" { roles = ["db_datareader", "SQLAgentReaderRole"] } } This block takes takes the following actions:https://docs.sqldsc.com/docs/pro-sql-script/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-sql-script/All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. SQL Script Usage # SQL Scripts are run using SQLCMD.EXE. That must be present on your system and in your path. Test Query # The simplest form of the test query is: resource "sql_script" "objects.sql" { script_file = "objects.sql" test_query = "SELECT * FROM sys.objects WHERE [name] = 'new_object'" } This expects the query to return one row.https://docs.sqldsc.com/docs/pro-precendence/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-precendence/PRO: Precedence Rules # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Precedence Rules # Adding domains and tags makes the precedence more complex. Each of these files can define the same configuration. For example, to configure node2 in this example, the following files would be used. Each lower file overrides the values in the higher file.https://docs.sqldsc.com/docs/pro-user-databases/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-user-databases/PRO: User Databases Block # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. User Databases Block # Starting in 1.36, the PRO Edition provides a mechanism to make identical changes across all user databases. This example creates a “ro” schema and a “ReadOnlyRole” in each user database. Then it grant the “ReadOnlyRole” EXEC permission on the schema and adds “ReadOnlyRole” to the db_datareader role in each database.https://docs.sqldsc.com/docs/pro-filtering/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-filtering/PRO: Filtering # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Filtering # The sqldsc.exe command has a filter for tag. When specified, it will only process nodes in that tag. This parameter is available for test and apply. Some sample command lines are: sqldsc.exe test --tag ag-one - Test the configuration on all servers assigned the ag-one tag.https://docs.sqldsc.com/docs/pro-for-versions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-for-versions/PRO: Filter for Versions # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Filter for Versions # Starting with 1.40.1, Resource Blocks support a for_versions attribute that allows resources to only apply to specific versions. That looks like this: resource "configuration" "cost_threshold" { name = "cost threshold for parallelism" value = 50 for_versions = ["2016", "2017", "2019"] } This configuration setting will only be applied if the target is one of the three listed versions.https://docs.sqldsc.com/docs/pro-queries/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-queries/All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Queries (BETA) # This is a BETA feature I am evaluating to see if it is useful You can run a simple query against your targets with the following syntax: sqldsc query dbcount.sql assuming dbcount.sql contains the following SELECT @@SERVERNAME AS [Server] ,COUNT(*) AS [Databases] FROM sys.https://docs.sqldsc.com/docs/pro-variables/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-variables/PRO: Variables # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Starting in 1.37, the PRO Edition allows variables to set attribute values. # tags/read-only.hcl login "placeholder" { login = "${read-only-account}" permissions = ["view server state"] user_databases { roles = ["db_datareader"] } } # tags/txn-ag.hcl # configure the nodes the txn-ag Availability Group variable "read-only-account" { value = "PROD\txn-ag-read-only" } # targets.https://docs.sqldsc.com/docs/pro-jobs/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-jobs/All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. SQL Server Agent Jobs (BETA) # These can be created using a job block. A simple job might look like this: job "TestJob" { step "update table" { database = "Reporting" command = <<EOF UPDATE dbo.HeartBeat SET LastProcessed = SYSDATETIMEOFFSET(); EOF } schedule "every minute" { frequency = "daily" interval = "1m" } } This creates a job named “TestJob” that runs every minute and updates the HeartBeat table in the Reporting database.https://docs.sqldsc.com/docs/pro-best-practices/Mon, 01 Jan 0001 00:00:00 +0000https://docs.sqldsc.com/docs/pro-best-practices/PRO: Best Practices # All features described on this page are part of the Professional Edition. You can purchase licenses for the Professional Edition on the Portal: https://portal.sqldsc.com. Domains # If you work with multiple domains, go all in on that. Have multiple DOMAIN.targets.hcl and NO targets.hcl Have domain specific directories under nodes and NO .hcl files under the root of nodes Tags # Common uses for Tags include: