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.

Outputs

PSCustomObject

Returns one object per SQL Server instance with comprehensive connection and environment diagnostics.

Properties:

• ComputerName: The resolved computer name of the SQL Server instance
• InstanceName: The SQL Server instance name (MSSQLSERVER for default instance)
• SqlInstance: The full SMO instance name (computer\instance format)
• SqlVersion: The SQL Server version number (e.g., 13.0.4001 for SQL Server 2016)
• ConnectingAsUser: The login name used to establish the SQL connection
• ConnectSuccess: Boolean indicating whether the SQL Server connection was successful
• AuthType: The type of authentication used (Windows Authentication or SQL Authentication)
• AuthScheme: The authentication scheme (KERBEROS, NTLM, SQL, etc.) or error if retrieval failed
• TcpPort: The TCP port number used by the SQL Server instance; contains error details if port detection failed
• IPAddress: The IP address of the target server
• NetBiosName: The fully qualified domain name (FQDN) of the server
• IsPingable: Boolean indicating whether the server responds to ICMP ping requests
• PSRemotingAccessible: Boolean indicating PSRemoting connectivity status; contains error details if test failed or skipped
• DomainName: The Active Directory domain name
• LocalWindows: The Windows OS version on the local machine where the command runs
• LocalPowerShell: The PowerShell version on the local machine
• LocalCLR: The CLR (Common Language Runtime) version on the local machine
• LocalSMOVersion: The SQL Server Management Objects (SMO) version on the local machine
• LocalDomainUser: Boolean indicating whether the local session is running as a domain user
• LocalRunAsAdmin: Boolean indicating whether the local session is running with administrator privileges
• LocalEdition: The PowerShell edition (Desktop or Core)