---
title: "Test-DbaConnection"
description: "Validates SQL Server connectivity and gathers comprehensive connection diagnostics"
url: "https://dbatools.io/Test-DbaConnection/"
availability: "Windows only"
tags: ["Connection"]
author: "Chrissy LeMaire (@cl), netnerds.net"
source: "https://github.com/dataplat/dbatools/blob/master/public/Test-DbaConnection.ps1"
last_updated: "2024-01-01"
---

# 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

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

```

## Examples

### Example 1: ComputerName : SQL2016 InstanceName : MSSQLSERVER SqlInstance : sql2016 SqlVersion : 13.0.4001...

```powershell
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: ComputerName : SQL2017 InstanceName : MSSQLSERVER SqlInstance : sql2017 SqlVersion : 14.0.3356...

```powershell
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.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | true (ByValue) |
| Default Value |  |

##### -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.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value |  |

##### -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.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value |  |

##### -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.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value | False |

##### -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.

| Property | Value |
| --- | --- |
| Alias |  |
| Required | False |
| Pipeline | false |
| Default Value | False |

## 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)

---

Part of [dbatools](https://dbatools.io/), a free and open source PowerShell module for SQL Server administration. Full command index: https://dbatools.io/commands/