System Administration

SQL Server Connection Diagnostics with sqlcmd

Prerequisites

Install sqlcmd (Linux/Ubuntu)

# Add Microsoft repository
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -

# For Ubuntu 22.04
curl https://packages.microsoft.com/config/ubuntu/22.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

# For Ubuntu 20.04
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

# Install
sudo apt-get update
sudo ACCEPT_EULA=Y apt-get install -y mssql-tools unixodbc-dev

# Add to PATH
echo 'export PATH="$PATH:/opt/mssql-tools/bin"' >> ~/.bashrc
source ~/.bashrc

Basic Connection Tests

1. Simple Connection Test

sqlcmd -S <server_address> -U <username> -P '<password>'

Example:

sqlcmd -S 192.168.1.100 -U sa -P 'MyPassword123'

Success: You’ll see a 1> prompt
Failure: Error message indicating the specific problem

2. Connection with Specific Port

sqlcmd -S tcp:<server_address>,<port> -U <username> -P '<password>'

Example:

sqlcmd -S tcp:192.168.1.100,1433 -U sa -P 'MyPassword123'

3. Connection to Specific Database

sqlcmd -S <server_address> -U <username> -P '<password>' -d <database_name>

Example:

sqlcmd -S 192.168.1.100 -U sa -P 'MyPassword123' -d MyDatabase

Common Connection Issues & Solutions

Issue 1: Certificate/Encryption Errors

Error: “SSL Provider: The certificate chain was issued by an authority that is not trusted”

Solution: Trust the server certificate

sqlcmd -S <server> -U <user> -P '<password>' -C

The -C flag tells sqlcmd to trust the server certificate without validation.

Issue 2: Connection Timeout

Error: “Login timeout expired” or “TCP Provider: Error code 0x102”

Solution 1: Increase timeout

sqlcmd -S <server> -U <user> -P '<password>' -l 30

The -l 30 sets a 30-second login timeout (default is 15 seconds).

Solution 2: Check basic connectivity first

# Test if port is open
telnet <server_address> 1433

# Or use netcat
nc -zv <server_address> 1433

Issue 3: Cannot Connect to Named Instance

Solution: Use instance name with backslash

sqlcmd -S <server><instance_name> -U <user> -P '<password>'

Example:

sqlcmd -S MYSERVERSQLEXPRESS -U sa -P 'MyPassword123'

Issue 4: Authentication Issues

For Windows Authentication:

sqlcmd -S <server> -E

The -E flag uses Windows Authentication (trusted connection).

Essential sqlcmd Flags

FlagDescriptionExample
-SServer address-S 192.168.1.100
-UUsername-U sa
-PPassword-P 'MyPass123'
-dDatabase name-d MyDatabase
-CTrust server certificate-C
-lLogin timeout (seconds)-l 30
-EWindows Authentication-E
-QExecute query and exit-Q "SELECT @@VERSION"
-iInput file with SQL-i script.sql
-oOutput file-o results.txt

Diagnostic Queries

Once connected (at the 1> prompt), run these queries:

Check SQL Server Version

SELECT @@VERSION;
GO

List All Databases

SELECT name, database_id, create_date 
FROM sys.databases
ORDER BY name;
GO

Check Current Database

SELECT DB_NAME() AS CurrentDatabase;
GO

List All Tables in Current Database

SELECT TABLE_SCHEMA, TABLE_NAME, TABLE_TYPE
FROM INFORMATION_SCHEMA.TABLES
WHERE TABLE_TYPE = 'BASE TABLE'
ORDER BY TABLE_SCHEMA, TABLE_NAME;
GO

Check Server Properties

SELECT 
    SERVERPROPERTY('ProductVersion') AS Version,
    SERVERPROPERTY('ProductLevel') AS ProductLevel,
    SERVERPROPERTY('Edition') AS Edition;
GO

Test Simple Query

SELECT GETDATE() AS CurrentDateTime;
GO

Exit sqlcmd

quit

Or press Ctrl+C

Complete Diagnostic Workflow

Step 1: Test Network Connectivity

# Check if port is open
telnet <server_address> 1433
# Press Ctrl+] then type 'quit' to exit

# Alternative with netcat
nc -zv <server_address> 1433

Step 2: Basic Connection

sqlcmd -S tcp:<server>,1433 -U <username> -P '<password>' -l 30

Step 3: If Certificate Error, Add -C

sqlcmd -S tcp:<server>,1433 -U <username> -P '<password>' -C -l 30

Step 4: Test Specific Database

sqlcmd -S tcp:<server>,1433 -U <username> -P '<password>' -C -l 30 -d <database_name>

Step 5: Run Diagnostic Queries

-- Version
SELECT @@VERSION;
GO

-- List databases
SELECT name FROM sys.databases;
GO

-- Switch database
USE MyDatabase;
GO

-- Check tables
SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_TYPE = 'BASE TABLE';
GO

quit

Quick One-Line Tests

Execute a query and exit immediately:

# Check if server is accessible
sqlcmd -S tcp:<server>,1433 -U <user> -P '<pass>' -C -Q "SELECT @@VERSION"

# List databases
sqlcmd -S tcp:<server>,1433 -U <user> -P '<pass>' -C -Q "SELECT name FROM sys.databases"

# Count tables in a database
sqlcmd -S tcp:<server>,1433 -U <user> -P '<pass>' -C -d MyDatabase -Q "SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLES"

Troubleshooting Tips

  1. Always start with telnet/netcat to confirm port is open
  2. Use -l 30 to avoid premature timeouts
  3. Add -C if you get certificate errors
  4. Use tcp: prefix to force TCP/IP protocol
  5. Check firewall rules if connection times out
  6. Verify SQL Server is running on the target machine
  7. Check SQL Server is configured to accept remote connections
  8. For SSH tunnels, connect to localhost with the forwarded port

Common Error Codes

ErrorMeaningSolution
Error code 0x102Connection timeoutIncrease timeout with -l 30
Error code 0x2749Named pipe errorUse TCP protocol: -S tcp:server,1433
Login failed for userAuthentication issueCheck username/password, database access
Cannot open databaseDatabase doesn’t exist or no accessCheck database name and permissions

Example: Complete SSH Tunnel Scenario

# On local machine: Create SSH tunnel
ssh -L 1433:remote-sql-server:1433 user@bastion-host -N -f

# Test connection through tunnel
sqlcmd -S tcp:localhost,1433 -U MyUser -P 'MyPassword' -C -l 30 -d MyDatabase

# Run a quick test
sqlcmd -S tcp:localhost,1433 -U MyUser -P 'MyPassword' -C -Q "SELECT DB_NAME()"

Notes

  • Always wrap passwords in single quotes to handle special characters
  • Use GO to execute SQL statements (required in sqlcmd)
  • Press Ctrl+C to cancel current command
  • Type quit or exit to leave sqlcmd
  • For scripting, use -Q for single queries or -i for SQL files