Testing a Database Connection with PowerShell

Generic checklist using fictitious addresses, sample users, and placeholder database names

Scope: This guide uses only example values. Replace them with the real server address, port, database name, and credentials in your own environment.

Example values used in this guide

The values below are placeholders for documentation and testing. Do not use real customer names, real public addresses, or production passwords in shared notes.

Field	Example value
Database host	192.0.2.10
Port	1433
Database name	SampleDatabase
Login name	sample_login
Password	Use a private password. Do not write it in shared documentation.

1. Test whether the port is reachable

Run this from the same workstation or server where the application runs. This confirms whether the machine can reach the database host over the expected TCP port.

Test-NetConnection 192.0.2.10 -Port 1433

Expected successful result:

TcpTestSucceeded : True

If the result is false, check the address, routing, firewall rules, and whether the database service is listening on the expected port.

2. Check whether the port is listening locally

Run this on the database host. It shows whether the host is listening on TCP port 1433.

Get-NetTCPConnection -LocalPort 1433

A listening result usually looks similar to this:

LocalAddress  LocalPort  State

0.0.0.0   1433   Listen

3. Test a full connection string with a login and password

A port test only proves network access. The following test proves that the server, database, login, password, and permissions work together.

$connectionString = @"

Server=tcp:192.0.2.10,1433;

Database=SampleDatabase;

User ID=sample_login;

Password=YourPrivatePasswordHere;

Encrypt=True;

TrustServerCertificate=True;

Connection Timeout=10;

"@

try {

    $conn = New-Object System.Data.SqlClient.SqlConnection $connectionString

    $conn.Open()

    Write-Host "Connection successful." -ForegroundColor Green

    $cmd = $conn.CreateCommand()

    $cmd.CommandText = "SELECT DB_NAME() + ' | ' + SUSER_SNAME()"

    Write-Host $cmd.ExecuteScalar()

}

catch {

    Write-Host "Connection failed: $($_.Exception.Message)" -ForegroundColor Red

}

finally {

    if ($conn) { $conn.Dispose() }

}

4. Test using the current signed-in identity

Use this when the application is expected to connect using the current user or service identity instead of a separate database login.

$connectionString = @"

Server=tcp:192.0.2.10,1433;

Database=SampleDatabase;

Integrated Security=True;

Encrypt=True;

TrustServerCertificate=True;

Connection Timeout=10;

"@

try {

    $conn = New-Object System.Data.SqlClient.SqlConnection $connectionString

    $conn.Open()

    Write-Host "Connection successful." -ForegroundColor Green

}

catch {

    Write-Host "Connection failed: $($_.Exception.Message)" -ForegroundColor Red

}

finally {

    if ($conn) { $conn.Dispose() }

}

5. Interpret common results

Message or symptom	What it usually means
TcpTestSucceeded : False	The port is not reachable from that machine. Check address, routing, firewall, and service status.
Connection timeout	The host may be unreachable, overloaded, blocked, or not listening on the selected port.
Login failed	The login name or password may be wrong, disabled, or not allowed for this server.
Cannot open database	The login works, but it does not have access to the selected database.
Certificate or trust error	Encryption is enabled but the certificate is not trusted by the client. For testing only, TrustServerCertificate=True can help isolate the issue.
Connection successful	The network path, port, database name, credentials, and basic permissions are working.

6. Quick checklist before escalating

[ ] Test from the same machine where the application runs.

[ ] Use the exact host, port, database name, and login expected by the application.

[ ] Confirm the database host is listening on the expected port.

[ ] Confirm the login is enabled and mapped to the correct database.

[ ] Avoid sharing real passwords, real customer names, or real addresses in screenshots or notes.

Recommended test order

1. Run Test-NetConnection to confirm the port is reachable.

2. Run Get-NetTCPConnection on the database host to confirm the service is listening.

3. Run the full connection-string test with the same credentials used by the application.

4. If the connection succeeds in PowerShell but fails in the application, compare the application host name, database name, authentication mode, and running identity.