Test-DbaConnection

Synopsis

Validates SQL Server connectivity and gathers comprehensive connection diagnostics

Description

Tests SQL Server instance connectivity while collecting detailed connection and environment information for troubleshooting. Returns authentication details, network configuration, TCP ports, and local PowerShell environment data. Essential for diagnosing connectivity issues before running automation scripts or validating access across multiple instances. Combines SQL connection testing with network diagnostics including ping status, PSRemoting access, and DNS resolution.

Syntax

Test-DbaConnection
    [[-SqlInstance] <DbaInstanceParameter[]>]
    [[-Credential] <PSCredential>]
    [[-SqlCredential] <PSCredential>]
    [-SkipPSRemoting]
    [-EnableException]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Test-DbaConnection SQL2016

ComputerName : SQL2016
InstanceName : MSSQLSERVER
SqlInstance : sql2016
SqlVersion : 13.0.4001
ConnectingAsUser : BASE\ctrlb
ConnectSuccess : True
AuthType : Windows Authentication
AuthScheme : KERBEROS
TcpPort : 1433
IPAddress : 10.2.1.5
NetBiosName : sql2016.base.local
IsPingable : True
PSRemotingAccessible : True
DomainName : base.local
LocalWindows : 10.0.15063.0
LocalPowerShell : 5.1.15063.502
LocalCLR : 4.0.30319.42000
LocalSMOVersion : 13.0.0.0
LocalDomainUser : True
LocalRunAsAdmin : False
LocalEdition : Desktop
Test connection to SQL2016 and outputs information collected

Example: 2

PS C:\> $winCred = Get-Credential sql2017\Administrator
PS C:\> $sqlCred = Get-Credential sa
PS C:\> Test-DbaConnection SQL2017 -SqlCredential $sqlCred -Credential $winCred

ComputerName : SQL2017
InstanceName : MSSQLSERVER
SqlInstance : sql2017
SqlVersion : 14.0.3356
ConnectingAsUser : sa
ConnectSuccess : True
AuthType : SQL Authentication
AuthScheme : SQL
TcpPort : 50164
IPAddress : 10.10.10.15
NetBiosName : sql2017.company.local
IsPingable : True
PSRemotingAccessible : True
DomainName : company.local
LocalWindows : 10.0.15063.0
LocalPowerShell : 5.1.19041.610
LocalCLR : 4.0.30319.42000
LocalSMOVersion : 15.100.0.0
LocalDomainUser : True
LocalRunAsAdmin : False
LocalEdition : Desktop
Test connection to SQL2017 instance and collecting information on SQL Server using the sa login, local Administrator account is used to collect port information

Optional Parameters

-SqlInstance

The target SQL Server instance or instances. This can be a collection and receive pipeline input to allow the function to be executed against multiple SQL Server instances.

-Credential

Windows credentials for computer-level access to the target server. Required for PSRemoting tests and TCP port detection when running under a different security context.
Use this when your current Windows account lacks administrative privileges on the target server or when testing across domain boundaries.

-SqlCredential

Login to the target instance using alternative credentials. Accepts PowerShell credentials (Get-Credential).
Windows Authentication, SQL Server Authentication, Active Directory - Password, and Active Directory - Integrated are all supported.
For MFA support, please use Connect-DbaInstance.

-SkipPSRemoting

Skips the PowerShell remoting connectivity test during the connection assessment.
Use this when PSRemoting is disabled or blocked by firewall rules but you still want to test SQL connectivity and gather other diagnostic information.

-EnableException

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.
This avoids overwhelming you with “sea of red” exceptions, but is inconvenient because it basically disables advanced scripting.
Using this switch turns this “nice by default” feature off and enables you to catch exceptions with your own try/catch.