Install dbatools and connect securely
The first command after installation is often also the first error message: Certificate failed chain validation. Since version 2, dbatools encrypts every connection and validates the server's certificate in the process. Most SQL Servers, however, have no certificate that the client trusts.
The quickest fix you will find for this is called Set-DbatoolsInsecureConnection. It works immediately. In our lab, though, it also turned encryption off, and the setting outlasted the session. This page shows the installation, the signature check and the ways through the certificate error, each with what actually happened in the lab.
In 60 seconds
- Install:
Install-Module dbatools -Scope CurrentUserfetches dbatools and the library dbatools.library. On Linux and macOS it needs PowerShell 7.4 or newer. Pin the version instead of updating blindly. - Signature: Since version 2.5.5, dbatools is signed through Azure Trusted Signing. You can check it with
Get-AuthenticodeSignature, but only on Windows. The command does not exist on Linux; there, the fallback is comparing the checksum with the PowerShell Gallery. - The certificate error is intentional. Since version 2 the rule is: encrypt and validate the certificate. Against a self-signed certificate, the connection failed the same way on SQL Server 2017, 2019, 2022 and 2025, and on Windows also with Windows authentication against the local instance.
-TrustServerCertificateper connection trusts the certificate and stays encrypted. In the lab, SQL Server reportedencrypt_option = TRUE.Set-DbatoolsInsecureConnectionturns encryption off (encrypt_option = FALSE) and, without-SessionOnly, applies permanently to the user. On Windows,Unregister-DbatoolsConfigremoved it again; on Linux only with-Scope FileUserLocal.-AllowTrustServerCertificateis meant to connect normally first and trust only after a certificate error. In the lab, this second attempt never kicked in.- Watch for warnings. With a failed connection,
Get-DbaDatabasereturned zero databases and two warnings, but no error.
1 · Install
dbatools is hosted on the PowerShell Gallery. On Windows, according to the project, Windows PowerShell 3 or newer is enough; on Linux and macOS it needs PowerShell 7.4 or newer. Installing for your own user needs no administrator rights:
# Install a specific version for the current user
Install-Module dbatools -RequiredVersion 2.9.1 -Scope CurrentUser
# What is installed?
Get-Module dbatools, dbatools.library -ListAvailable | Select-Object Name, VersionSince version 2, the module dbatools.library comes with it. It contains the .NET libraries that dbatools uses, including SMO and the Microsoft.Data.SqlClient driver. Install-Module dbatools fetches it automatically; dbatools 2.9.1 requires dbatools.library 2026.9.14 or newer. It is the larger part: 304 MB unpacked, against 31 MB for dbatools itself.
Pin the version. A new release can change defaults and parameters; version 2.8.0, for example, changed the parameter form of Install-DbaMaintenanceSolution. On servers and in pipelines, install a specific version, update deliberately, and test your scripts beforehand.
Without internet: According to the project, you download the module on a machine with internet using Save-Module dbatools -Path <folder> and copy the folder into a module folder on the target machine. The README names C:\Program Files\WindowsPowerShell\Modules for all users and $HOME\Documents\WindowsPowerShell\Modules for your own account; in general, any path listed in $env:PSModulePath works. For our lab, we downloaded the two packages directly from the Gallery, compared their checksums with the ones listed there, and then mounted them into the container. The import took 6.2 seconds and printed no warning.
2 · Check the signature
Since version 2.5.5, dbatools is signed through Azure Trusted Signing; before that, with a certificate from DigiCert. Because issuer and root certificate changed, PowerShellGet, according to the maintainers, requires -SkipPublisherCheck once when you upgrade from an older version. After that, you should check the signature of the installed files yourself:
# Windows only: count the signature status of all module files
$m = Get-Module dbatools -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1
Get-ChildItem (Split-Path $m.Path) -Recurse -File -Include *.ps1, *.psm1, *.psd1, *.dll |
Get-AuthenticodeSignature | Group-Object Status | Select-Object Name, CountOur check on 13 November 2026 ran under Windows PowerShell over both modules. All signed files had the status Valid. Two copies of a bundled third-party library (Bogus.dll) were NotSigned. The signer was CN=dbatools, O=dbatools, L=Vienna, S=Virginia, C=US, issued by CN=Microsoft ID Verified CS EOC CA 04.
The signing certificate of dbatools 2.9.1 was valid only until 17 October 2026. The signature remains valid anyway because it carries a timestamp; without one, it would expire with the certificate (Microsoft). On Windows, Get-AuthenticodeSignature still showed Valid on 17 November 2026, a month after expiry. According to the maintainers, the certificate changes daily with Azure Trusted Signing. If you work with the execution policies AllSigned or RemoteSigned, you may therefore have to trust the publisher again after updates. We did not reproduce this.
On Linux, Get-AuthenticodeSignature does not exist; Microsoft lists the command as available on Windows only. PowerShell reports that the command is unknown (… is not recognized as a name of a cmdlet …). There, the fallback is comparing the package's checksum with the value on the Gallery page, or you check the signature once on Windows and then distribute exactly those files.
3 · Why the first connection fails
dbatools follows the defaults of the Microsoft.Data.SqlClient driver. According to the maintainers, the requirement that the server's certificate be valid (TrustServerCertificate=False) has applied since dbatools 1.1. Version 2.0 added encryption as the default (Encrypt=True), which Microsoft introduced with SqlClient 4.0 (release notes 4.0). According to Microsoft, a SQL Server without its own trusted certificate generates a self-signed one at startup. The client does not trust it, and its name usually does not match the server name either. In our lab, it looked like this:
$cred = Get-Credential sa
Connect-DbaInstance -SqlInstance sql2022 -SqlCredential $credError connecting to [sql2022]: Certificate failed chain validation. Error(s): 'self-signed certificate, [Status: UntrustedRoot]
'.
Certificate name mismatch. The provided 'DataSource' or 'HostNameInCertificate' does not match the name in the certificate.Below that is the driver's message: A connection was successfully established with the server, but then an error occurred during the pre-login handshake. So the connection was established. It failed only at the certificate check. SQL Server 2017, 2019, 2022 and 2025 behaved the same. So this is not a version problem but the intended default.
Most commands do not throw an error. Connect-DbaInstance aborts by default. Other commands such as Get-DbaDatabase only print a warning and carry on:
Get-DbaDatabase -SqlInstance sql2022 -SqlCredential $cred[06:19:33][Connect-DbaInstance] Failure | Error connecting to [sql2022]: Certificate failed chain validation. …
[06:19:33][Get-DbaDatabase] Failure | Certificate failed chain validation. …These are the two warnings, shortened. On Windows, with Windows authentication against the local instance of a freshly installed SQL Server 2022, the reason read The certificate chain was issued by an authority that is not trusted, again with two warnings and no results. Zero databases came back. A script that only checks for errors reads this as "no databases". Many commands have the switch -EnableException, which turns the warning into an error; for scripts, this is the safe choice. With Connect-DbaInstance it is the other way round: The command throws on its own, and -DisableException turns that into a warning.
4 · Three ways through the certificate error
| Way | Encrypted? | Applies to | When |
|---|---|---|---|
| Proper certificate on the server (trusted authority, matching name) | yes, validated | all clients | Production |
-TrustServerCertificate when connecting | yes, without validating the certificate | this one connection | Lab, test, transition |
Set-DbatoolsInsecureConnection | no | all connections of the user, permanently; with -SessionOnly only the session | not recommended |
In the lab, we tried each variant against all four versions. The column encrypt_option comes from sys.dm_exec_connections for the respective connection:
Call of Connect-DbaInstance | 2017 | 2019 | 2022 | 2025 | encrypt_option |
|---|---|---|---|---|---|
| without extras | error | error | error | error | – |
-TrustServerCertificate | ok | ok | ok | ok | TRUE |
-AllowTrustServerCertificate | error | error | error | error | – |
-EncryptConnection:$false | ok | ok | ok | ok | FALSE |
after Set-DbatoolsInsecureConnection | ok | ok | ok | ok | FALSE |
We measured the last row against 2022. On Windows, with Windows PowerShell 5.1 and Windows authentication, -TrustServerCertificate showed the same: encrypt_option = TRUE, authenticated via NTLM.
Production: a proper certificate
In the long run, the server needs a certificate that the clients trust and whose name matches the connection name. Then the defaults work without any extras. For this, the maintainers name dedicated commands, such as New-DbaComputerCertificate, Set-DbaNetworkCertificate and Enable-DbaForceNetworkEncryption; they set up the certificate on Windows servers. On Linux, you set it up with mssql-conf. We did not build either in the lab.
Lab: -TrustServerCertificate per connection
The connection stays encrypted; only the certificate validation is skipped. Open the connection once and pass the connection object on to the following commands:
$cred = Get-Credential sa
$s = Connect-DbaInstance -SqlInstance sql2022 -SqlCredential $cred -TrustServerCertificate
Get-DbaDatabase -SqlInstance $s # uses the open connection
$s.Query("SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID")In the lab, the four system databases came back, and encrypt_option was TRUE.
One exception: Some commands internally open a new connection via the instance name and do not take over the trust setting of the connection object. This was the case with Test-DbaLastBackup (Part 4). There, only the configuration for the current session helps:
# This PowerShell session only: do not validate the certificate, encryption stays on
Set-DbatoolsConfig -FullName sql.connection.trustcert -Value $trueSet-DbatoolsConfig alone does not save anything. A value becomes permanent only with Register-DbatoolsConfig; that is exactly what Set-DbatoolsInsecureConnection does without -SessionOnly (source code 2.9.1). In the lab, the connection stayed encrypted with this setting.
5 · What Set-DbatoolsInsecureConnection really does
The command sets two values: sql.connection.trustcert to true and sql.connection.encrypt to false. The second value is the one that is easy to overlook. We measured in six consecutive PowerShell sessions of the same user, each time with a connection without extras against SQL Server 2022:
| Step | Configuration afterwards | Connection without extras |
|---|---|---|
Set-DbatoolsInsecureConnection -SessionOnly | encrypt off, trustcert on | ok, unencrypted |
| new session | defaults restored | certificate error |
Set-DbatoolsInsecureConnection | encrypt off, trustcert on | ok, unencrypted |
| new session | encrypt off, trustcert on | ok, unencrypted: still applies |
Unregister-DbatoolsConfig … -Scope FileUserLocal | file deleted | – |
| new session | defaults restored | certificate error |
So even -SessionOnly turns encryption off, just not permanently. On Linux, dbatools stores the permanent setting in ~/.config/PowerShell/dbatools/psf_config.json:
[
{
"Type": 2,
"Style": "default",
"Version": 1,
"Value": "false",
"FullName": "sql.connection.encrypt"
},
{
"Type": 2,
"Style": "default",
"Version": 1,
"Value": "true",
"FullName": "sql.connection.trustcert"
}
]Way back on Linux:
Unregister-DbatoolsConfig -FullName sql.connection.trustcert, sql.connection.encrypt -Scope FileUserLocalWithout -Scope, the same command failed on Linux with a message that does not point to the cause:
Cannot process argument transformation on parameter 'EnableException'. Cannot convert value "" to type "System.Boolean". Boolean parameters accept only Boolean values and numbers, such as $True, $False, 1 or 0.With -Scope FileUserShared, it ran through without an error, but the file stayed.
On Windows, dbatools writes the permanent setting to the user's registry. In the lab, it sat under HKEY_CURRENT_USER\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config\Default with the values sql.connection.trustcert and sql.connection.encrypt. A new session then connected without any option and without encryption (encrypt_option = FALSE). Here the command without -Scope was enough:
Unregister-DbatoolsConfig -FullName sql.connection.trustcert, sql.connection.encryptIn the next session, the defaults applied again: sql.connection.encrypt set to True, sql.connection.trustcert to False. For scripts that run on both systems, this means: check the way back per operating system and do not assume it looks the same everywhere.
Assessment: For a throwaway lab, Set-DbatoolsInsecureConnection is convenient, and discussions in the project also recommend it for self-signed certificates (example). Anyone who uses it should know that all later connections of this user then run unencrypted, including those to servers with a good certificate. It does not belong on workstations and servers from which you manage production.
6 · -AllowTrustServerCertificate: a good idea, but it does not take effect in the lab
Since the end of 2025, Connect-DbaInstance has the switch -AllowTrustServerCertificate, introduced at the request of the community (#10006). The idea: connect normally first and start a second attempt with trust only after a certificate error. That would be the ideal middle ground for mixed environments.
In the lab, the connection with this switch failed on all four versions exactly as it did without it. The cause is in the source code of 2.9.1 (Connect-DbaInstance.ps1, lines 1434–1439): The second attempt starts only if the error message contains one of the words certificate, SSL, TLS or trust. But only the outermost message is checked. We rebuilt that spot:
Exception calling "ExecuteWithResults" with "1" argument(s): "Failed to connect to server sql2022."
ConnectionFailureException: Failed to connect to server sql2022.
SqlException: A connection was successfully established with the server, but then an error occurred during the pre-login handshake. …
AuthenticationException: Certificate failed chain validation. …The reference to the certificate appears only in the innermost exception; the outer message contains none of the search words. Our client was PowerShell 7 on Linux with SqlClient 7.0. We did not check on Windows. Because the outer message comes from SMO and PowerShell, we suspect the same behavior there. As of 16 November 2026, the finding had not been reported in the project, and the spot was unchanged in the development version.
Until this is clarified: Do not plan on -AllowTrustServerCertificate as a middle ground, but decide deliberately: set up a certificate, or use -TrustServerCertificate for exactly those targets where you accept the risk.
7 · Credentials
-SqlCredentialpasses a SQL login,-Credentiala Windows credential for access to the host (for services or files, for example). Without-SqlCredential, dbatools tries the current user's Windows login.- Interactive:
Get-Credentialasks for the password without it ending up in the history. - In scripts: On Windows,
Export-Clixmlprotects a credential object with DPAPI; it can be read only by the same user on the same machine. On Linux and macOS, the password is stored in plain text in the file. According to Microsoft,Export-Clixmlencrypts credentials only on Windows. There you need a different store, such as a vault through the SecretManagement module with a suitable extension, or file permissions that let only the service user read it. We did not reproduce this in the lab. - Logs: dbatools writes messages to
~/.local/share/PowerShell/dbatools/on Linux and to%APPDATA%\PowerShell\dbatools\on Windows. On Linux, the password of our SQL test login was in none of the seven files. The Windows run used Windows authentication and says nothing about this.
8 · Before the first command that writes
- Read the help:
Get-Help Test-DbaLastBackup -Fullshows parameters, default values and examples; in addition, there is a page per command athttps://dbatools.io/<command>.Find-DbaCommandsearches commands by keyword. -WhatIffirst: Commands that change something show with-WhatIfwhat they would do, without doing it.-Confirmasks before each step.- A test target first: Try new commands against a test instance or a container, not against production. Even read-only checks can generate load.
- Check the results: Evaluate warnings or set
-EnableExceptionwhere the command offers it (section 3).
What we measured and what we did not
- Measured (13 and 16 November 2026): dbatools 2.9.1 with dbatools.library 2026.9.14 (SqlClient 7.0, SMO 18.100) under PowerShell 7.6.8 in a Linux container; SQL Server 2017 CU31, 2019 CU32, 2022 CU27 and 2025 CU9 in Linux containers without their own certificate. Signature check under Windows PowerShell on a workstation.
- Measured on Windows (Nov 17, 2026): the same module versions under Windows PowerShell 5.1 on Windows Server 2022, as administrator with Windows authentication against a local SQL Server 2022 RTM without its own certificate. We checked the signature (all signed module files
Valid), import, the certificate error,-TrustServerCertificate, andSet-DbatoolsInsecureConnectionwith its storage and the way back. - Not measured: installation via
Install-Moduleon Windows, execution policies and-SkipPublisherCheck(from the maintainers' README and blog);-AllowTrustServerCertificateon Windows, because the test step was faulty; PowerShell 7 on Windows; a server with a certificate from a real certificate authority;Encrypt=Strictwith TDS 8.0.
Further reading
- dbatools: README with installation, New defaults for SQL Server connections (rationale for the defaults), dbatools and Azure Trusted Signing, help for Set-DbatoolsInsecureConnection.
- Microsoft: Microsoft.Data.SqlClient 4.0 release notes (
Encrypton by default), Configure SQL Server encryption (self-signed fallback certificate), Get-AuthenticodeSignature, Export-Clixml. - At PSG: dbatools overview, Part 3: What
Test-Dbareally tells you, Part 4: Prove your backups actually restore, SQL Server on Linux for Windows admins.