Skip to main content
The SQL Query Stress GUI application provides a user-friendly interface for load testing SQL Server queries. This guide walks through the complete workflow from setup to execution.

​
Prerequisites

The tool runs on any Windows machine with the .NET 8.0 runtime installed. Download the latest version from GitHub releases.

​
Main Interface

The GUI is organized into several key sections:
  • Query Editor: SQL editor with syntax highlighting for your test queries
  • Database Settings: Connection configuration panel
  • Load Settings: Thread and iteration controls
  • Results Dashboard: Real-time metrics and statistics
  • Control Buttons: Start, stop, and utility actions

​
Step-by-Step Workflow

1

Configure Database Connection

Click the Database button to open the connection dialog.Configure your connection settings:
  • Server: Your SQL Server instance (e.g., (local), .\SQLEXPRESS)
  • Authentication: Choose between Windows Authentication or SQL Server Authentication
  • Database: Select the target database for your test
  • Advanced: Configure connection timeout, pooling, and encryption options
Test the connection to ensure it’s working before proceeding.
2

Write Your Query

Enter your T-SQL query in the main editor window. You can:
  • Type directly into the editor
  • Paste from SQL Server Management Studio
  • Load from a saved settings file
If you select text in the query editor before running, only the selected text will be executed. This is useful for testing specific portions of larger scripts.
SELECT * FROM Customers WHERE Region = @Region
3

Configure Load Parameters

Set your load testing parameters:Number of Threads: Simulates concurrent users executing the query
  • Default: 1
  • Range: 1 to 1000+
  • Higher values create more load on the server
Iterations per Thread: How many times each thread executes the query
  • Default: 1
  • Each thread runs this many times independently
  • Total executions = Threads × Iterations
Delay Between Queries (ms): Optional pause between iterations
  • Default: 0 (no delay)
  • Useful for simulating realistic user behavior
  • Value in milliseconds
4

Configure Options (Optional)

Click File → Options to access advanced settings:
  • Collect I/O Stats: Captures logical reads per query (default: enabled)
  • Collect Time Stats: Records CPU and elapsed time (default: enabled)
  • Force Data Retrieval: Forces all result rows to be processed (default: disabled)
  • Connection Timeout: Seconds to wait when establishing connections (default: 15)
  • Command Timeout: Query execution timeout in seconds (default: 0 = unlimited)
  • Kill Queries on Cancel: Immediately cancel running queries when stopped (default: enabled)
5

Set Up Parameterization (Optional)

If your query uses parameters, click the Parameters button to configure:
  • Define a parameter query that returns test values
  • Map query parameters to columns from the parameter query
  • Each thread iteration gets the next row from the parameter result set
See Query Parameterization for detailed instructions.
6

Run the Test

Click the GO button to start the load test.During execution, you’ll see real-time updates:
  • Active Threads: Currently running threads
  • Iterations Completed: Total executions so far
  • Progress Bar: Visual indicator of completion
  • Elapsed Time: Total test duration
  • Live Metrics: CPU time, elapsed time, logical reads updating in real-time
The test runs until all threads complete their iterations or you click Cancel.
7

Review Results

After the test completes, review the metrics:
  • CPU Seconds/Iteration (Avg): Average CPU time per execution
  • Actual Seconds/Iteration (Avg): Average elapsed time from SQL Server’s perspective
  • Client Seconds/Iteration (Avg): Average time measured by the client
  • Logical Reads/Iteration (Avg): Average disk reads per execution
  • Total Exceptions: Click to view any errors that occurred
See Interpreting Results for guidance on using these metrics.

​
Utility Features

​
Clear Buffers

Click Clear Buffers to execute: 
CHECKPOINT
DBCC DROPCLEANBUFFERS
This clears SQL Server’s buffer cache, ensuring your test measures actual disk I/O rather than cached data.
Only use this feature in test environments. Never clear buffers on production servers as it will impact performance for all users.

​
Free Cache

Click Free Cache to execute: 
DBCC FREEPROCCACHE
This clears the procedure cache, forcing query plans to be recompiled. Useful when testing plan optimization.

​
Export Results

Save your test results for later analysis:
  • File → Export Results → To Text: Appends results to a text file
  • File → Export Results → To CSV: Appends results to a CSV file for Excel/analysis tools
  • File → Export Results → To Clipboard: Copies results to clipboard
Results include test ID, timestamp, all metrics, and configuration parameters.

​
Saving and Loading Settings

​
Save Settings

  1. Click File → Save Settings
  2. Choose a location and filename (.json extension)
  3. Settings file includes:
    • Query text
    • Connection information
    • Thread/iteration configuration
    • All options and parameters

​
Load Settings

  1. Click File → Load Settings
  2. Select a previously saved .json file
  3. All settings are restored, including the query
Save different configurations for different test scenarios. For example, save “light-load.json” with 5 threads and “heavy-load.json” with 100 threads.

​
Command Line Automation

You can launch the GUI with pre-loaded settings: 
SQLQueryStress.exe -s "path\to\settings.json"
For fully automated testing without the GUI, use the CLI tool instead. See Using the CLI Tool.

​
Best Practices

  1. Start Small: Begin with 1 thread and 1 iteration to verify your query works
  2. Increase Gradually: Slowly increase threads to find breaking points
  3. Monitor Server: Watch SQL Server performance metrics during tests
  4. Test Realistic Scenarios: Use actual production parameters and data volumes
  5. Save Baselines: Export results before making optimizations to compare against
  6. Clear Caches: Clear buffers between tests for consistent results

​
Next Steps

Query Parameterization

Learn how to test queries with dynamic parameter values

Interpreting Results

Understand metrics and optimize based on results

Connection Settings

Configure connection settings for SSMS compatibility

Using the CLI

Automate tests with the command-line tool

Build docs developers (and LLMs) love

Get started for freeTalk to us