PRO: Roles #

All features described in this page are part of the Professional Edition.
While in beta, you can enable the Professional Edition by creating an empty key.xt file next to the sqldsc.exe file.
The PRO edition will become a paid version. Until then, PRO features expire 90 days after the build date. Please see https://www.scalesql.com for updated builds or run sqldsc update.

Breaking change in 1.36 #

The attribute names that Targets use to add to and override the default roles have changed to make them simpler and more explicit.

The target_defaults block in a Targets file can define an array of roles using the roles attribute. Targets can override these or add more roles. This is unchanged.

Prior to version 1.36, a Target could have one of the following two attributes
- added_roles – roles that are added to any default roles
- roles – set the list of roles for this target
Starting in version 1.36, a Target can have one of the two following attributes
- add_roles – roles that are added to any default roles
- only_roles – set the list of roles for this target

Updating your repository #

For targets, rename roles = [...] to only_roles = [...] EXCEPT in the target_defaults block For targets, rename added_roles = [...] to add_roles = [...]
For target_defaults, no changes are needed
In /config/state/repository.toml, update the version to 2 (version=2). This is a new file created by this version and will need to checked into your repository.

The documentation for the earlier behavior is further down the page.

Roles #

Each target can be assigned multiple roles. Instances in roles can be given identical configuration. Good uses of roles 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.hcl file looks something like this

target_defaults {
    roles = ["baseline"]
}

target "D40\SQL2016" {}

target "server1.domain1.com" {
    only_roles = ["baseline", "data-center-1"]
}

target "node1.domain1.com" {
    only_roles = ["prod", "data-center-2", "ag-one"]
}

target "server04" {
    add_roles = ["local-backups"]
}

The target_defaults section can define a base set of roles for every target.
The only_roles field for a target overrides the roles field in the target_defaults. In the example, node1 has three roles and doesn’t have the baseline role.
The add_roles field adds the roles to the default roles. In the example, server04 ends up with two roles: baseline and local-backups.
Because the target_defaults block is per file (i.e. per domain), each domain can get a different set of default roles.

Role Order Matters #

The Resources from the roles are processed in order the roles are specified
List more general roles followed by more specific
Remember that Resource in later roles can override resources in earlier roles

Configuration #

The name of a role must match a file name in the roles directory. The init command doesn’t create the roles folder.

config\
    nodes\
        DOMAIN1\   
            node1.hcl
            server1.hcl
    roles\
        ag-one.hcl
        baseline.hcl
        data-center-1.hcl
        data-center-2.hcl
        prod.hcl
    defaults.hcl
    targets.hcl
    DOMAIN1.targets.hcl

Roles (prior to 1.36) #