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
| Flag | Description | Example |
|---|---|---|
-S | Server address | -S 192.168.1.100 |
-U | Username | -U sa |
-P | Password | -P 'MyPass123' |
-d | Database name | -d MyDatabase |
-C | Trust server certificate | -C |
-l | Login timeout (seconds) | -l 30 |
-E | Windows Authentication | -E |
-Q | Execute query and exit | -Q "SELECT @@VERSION" |
-i | Input file with SQL | -i script.sql |
-o | Output 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
- Always start with telnet/netcat to confirm port is open
- Use
-l 30to avoid premature timeouts - Add
-Cif you get certificate errors - Use
tcp:prefix to force TCP/IP protocol - Check firewall rules if connection times out
- Verify SQL Server is running on the target machine
- Check SQL Server is configured to accept remote connections
- For SSH tunnels, connect to
localhostwith the forwarded port
Common Error Codes
| Error | Meaning | Solution |
|---|---|---|
| Error code 0x102 | Connection timeout | Increase timeout with -l 30 |
| Error code 0x2749 | Named pipe error | Use TCP protocol: -S tcp:server,1433 |
| Login failed for user | Authentication issue | Check username/password, database access |
| Cannot open database | Database doesn’t exist or no access | Check 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
GOto execute SQL statements (required in sqlcmd) - Press
Ctrl+Cto cancel current command - Type
quitorexitto leave sqlcmd - For scripting, use
-Qfor single queries or-ifor SQL files







