Using the CLI Tool - SQL Query Stress

The sqlstresscmd command-line tool provides a cross-platform way to automate SQL query stress testing. It uses the same load engine as the GUI application but can run on Windows, Linux, and macOS.

Installation

Download the appropriate version for your platform from GitHub releases. The tool requires the .NET 8.0 runtime.

Quick Start

Run a simple test with a configuration file:

sqlstresscmd -s settings.json

Command-Line Options

sqlstresscmd supports the following command-line arguments:

-s, --settingsFile

string

Path to a saved session settings file (.json format). This file contains all configuration including connection info, query, threads, and iterations.

sqlstresscmd -s "mytest.json"

-d, --dbserver

string

Database server to connect to. Overrides the server specified in the settings file.

sqlstresscmd -s settings.json -d "localhost\\SQLEXPRESS"

-t, --threads

integer

Number of concurrent threads to use. Overrides the thread count in the settings file.Default: 1

sqlstresscmd -s settings.json -t 10

-i, --input

string

Path to a .sql script file to execute. Overrides the query in the settings file.

sqlstresscmd -s settings.json -i "query.sql"

-r, --results

string

Automatically save results to the specified file. Supports text or CSV format based on file extension.

sqlstresscmd -s settings.json -r "results.csv"

-x, --xtract

boolean

Extract the sample.json configuration file template to the current directory.

sqlstresscmd -x

Configuration File Format

The settings file is a JSON document with the following structure. Use sqlstresscmd -x to extract a template.

Sample Configuration

sample.json

{
  "CollectIoStats": true,
  "CollectTimeStats": true,
  "CommandTimeout": 0,
  "ConnectionTimeout": 15,
  "DelayBetweenQueries": 0,
  "EnableConnectionPooling": true,
  "ForceDataRetrieval": false,
  "KillQueriesOnCancel": true,
  "MainDbConnectionInfo": {
    "ApplicationIntent": 0,
    "ConnectTimeout": 15,
    "Database": "Northwind",
    "EnablePooling": true,
    "IntegratedAuth": false,
    "Login": "dbUser",
    "MaxPoolSize": 2,
    "Password": "!Se8ret",
    "Server": ".\\SQLEXPRESS"
  },
  "MainQuery": "SELECT * FROM Customers",
  "NumIterations": 10,
  "NumThreads": 1,
  "ParamDbConnectionInfo": {
    "ApplicationIntent": 0,
    "ConnectTimeout": 0,
    "Database": "",
    "EnablePooling": true,
    "IntegratedAuth": true,
    "Login": "",
    "MaxPoolSize": 0,
    "Password": "",
    "Server": ""
  },
  "ParamMappings": [],
  "ParamQuery": "",
  "ShareDbSettings": true
}

Configuration Properties

Load Settings

NumThreads: Number of concurrent threads (default: 1)
NumIterations: Number of times each thread executes the query (default: 1)
DelayBetweenQueries: Milliseconds to wait between iterations (default: 0)

Query Settings

MainQuery: The T-SQL query to execute
CommandTimeout: Query timeout in seconds (0 = unlimited)
ForceDataRetrieval: Force reading all result rows (default: false)

Connection Settings

Server: SQL Server instance name
Database: Database name
IntegratedAuth: Use Windows Authentication (default: true)
Login: SQL Server login (if not using Windows Auth)
Password: SQL Server password (if not using Windows Auth)
ConnectTimeout: Connection timeout in seconds (default: 15)
EnablePooling: Enable connection pooling (default: true)
MaxPoolSize: Maximum connections in pool (0 = default)
ApplicationIntent: 0 = ReadWrite, 1 = ReadOnly

Statistics Collection

CollectIoStats: Capture logical reads (default: true)
CollectTimeStats: Capture CPU and elapsed time (default: true)

Advanced Settings

KillQueriesOnCancel: Immediately cancel queries on Ctrl+C (default: true)
ConnectionTimeout: Connection establishment timeout

Usage Examples

Extract Sample Configuration

Generate a template configuration file:

sqlstresscmd -x

This creates sample.json in the current directory.

Run with Configuration File

Execute a test using saved settings:

sqlstresscmd -s production-test.json

Override Server

Test against a different server than specified in config:

sqlstresscmd -s settings.json -d "prod-server.database.windows.net"

Override Thread Count

Run with more threads than the saved configuration:

sqlstresscmd -s settings.json -t 50

Use External SQL File

Execute a query from a file instead of the config:

sqlstresscmd -s settings.json -i "stored-proc-test.sql"

The stored-proc-test.sql file:

EXEC dbo.GetCustomerOrders @CustomerId = 12345

Save Results Automatically

Export results to CSV for analysis:

sqlstresscmd -s settings.json -r "results.csv"

For text format:

sqlstresscmd -s settings.json -r "results.txt"

Combine Multiple Overrides

Run against a different server with more threads and save results:

sqlstresscmd -s baseline.json -d "test-server" -t 100 -r "high-load-test.csv"

Output Format

The CLI displays results in a formatted table:

┌─────────────────────────────────────┬────────────────────────┐
│ sqlstresscmd result                 │                  Value │
├─────────────────────────────────────┼────────────────────────┤
│ Start time                          │ 2026-03-05 14:23:45Z   │
│ Elapsed time                        │ 00:00:12.3456          │
│ Number of Threads                   │                     10 │
│ Iterations Completed                │                    100 │
│ CPU Seconds/Iteration (Avg)         │                 0.0234 │
│ Actual Seconds/Iteration (Avg)      │                 0.1234 │
│ Client Seconds/Iteration (Avg)      │                 0.1250 │
│ Logical Reads/Iteration (Avg)       │                145.670 │
└─────────────────────────────────────┴────────────────────────┘

CSV Export Format

When using -r results.csv, the output includes:

TestId,TestStartTime,ElapsedTime,Iterations,Threads,Delay,CompletedIterations,AvgCPUSeconds,AvgActualSeconds,AvgClientSeconds,AvgLogicalReads
a1b2c3d4...,2026-03-05 14:23:45,00:00:12.3456,100,10,0,100,0.0234,0.1234,0.1250,145.670

Results are appended to the file, allowing you to build a history of test runs:

# Run multiple tests, all appending to the same CSV
sqlstresscmd -s baseline.json -r history.csv
sqlstresscmd -s optimized.json -r history.csv
sqlstresscmd -s final.json -r history.csv

Automation Examples

Continuous Integration

Run as part of a CI/CD pipeline:

#!/bin/bash
# performance-test.sh

echo "Running SQL performance tests..."
sqlstresscmd -s tests/query-performance.json -r "results/test-${BUILD_NUMBER}.csv"

if [ $? -eq 0 ]; then
    echo "Performance test passed"
else
    echo "Performance test failed"
    exit 1
fi

Progressive Load Testing

Test with increasing thread counts:

#!/bin/bash
for threads in 1 5 10 25 50 100; do
    echo "Testing with $threads threads..."
    sqlstresscmd -s baseline.json -t $threads -r "progressive-load.csv"
    sleep 5
done

Compare Before/After Optimization

#!/bin/bash
# Test before optimization
echo "Testing before optimization..."
sqlstresscmd -s query-test.json -r "before.csv"

# Apply index or schema change
sqlcmd -S localhost -d MyDB -i "add-index.sql"

# Test after optimization
echo "Testing after optimization..."
sqlstresscmd -s query-test.json -r "after.csv"

echo "Compare before.csv and after.csv to see improvement"

Best Practices

Use Version Control for Configuration Files

Store your .json configuration files in version control alongside your database schema. This creates a history of performance tests and makes it easy to rerun historical tests.

Separate Configs for Different Scenarios

Create different configuration files for different test scenarios:

smoke-test.json - Quick validation with low load
baseline.json - Standard load for comparisons
stress-test.json - Maximum load to find limits

Use Environment Variables for Secrets

Don’t store passwords in configuration files. Use environment variables or secure secret management:

# Set password via environment
export DB_PASSWORD="SecurePassword123"

# Update config at runtime or use a secrets manager

Save Results with Timestamps

Include timestamps in result filenames:

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
sqlstresscmd -s test.json -r "results_${TIMESTAMP}.csv"

Troubleshooting

Connection Failures

If connection fails:

Verify the server name and instance
Check if SQL Server allows remote connections
Verify firewall rules allow the connection
Test with sqlcmd or the GUI tool first

Authentication Issues

For Windows Authentication:

Set "IntegratedAuth": true
Omit Login and Password

For SQL Server Authentication:

Set "IntegratedAuth": false
Provide Login and Password

Timeout Errors

If queries timeout:

Increase CommandTimeout in the config
Set to 0 for unlimited timeout (use with caution)
Verify the query executes successfully in SSMS

Next Steps

Query Parameterization

Learn how to use parameters in CLI tests

Interpreting Results

Understand the metrics from your tests

Connection Settings

Configure connection settings and SSMS compatibility

Using the GUI

Use the Windows GUI for interactive testing

Get Started

Guides

Configuration

Advanced

Reference

​Installation

​Quick Start

​Command-Line Options

​Configuration File Format

​Sample Configuration

​Configuration Properties

​Load Settings

​Query Settings

​Connection Settings

​Statistics Collection

​Advanced Settings

​Usage Examples

​Extract Sample Configuration

​Run with Configuration File

​Override Server

​Override Thread Count

​Use External SQL File

​Save Results Automatically

​Combine Multiple Overrides

​Output Format

​CSV Export Format

​Automation Examples

​Continuous Integration

​Progressive Load Testing

​Compare Before/After Optimization

​Best Practices

​Troubleshooting

​Connection Failures

​Authentication Issues

​Timeout Errors

​Next Steps

Query Parameterization

Interpreting Results

Connection Settings

Using the GUI

Build docs developers (and LLMs) love

Installation

Quick Start

Command-Line Options

Configuration File Format

Sample Configuration

Configuration Properties

Load Settings

Query Settings

Connection Settings

Statistics Collection

Advanced Settings

Usage Examples

Extract Sample Configuration

Run with Configuration File

Override Server

Override Thread Count

Use External SQL File

Save Results Automatically

Combine Multiple Overrides

Output Format

CSV Export Format

Automation Examples

Continuous Integration

Progressive Load Testing

Compare Before/After Optimization

Best Practices

Troubleshooting

Connection Failures

Authentication Issues

Timeout Errors

Next Steps