SQL Stress

Database load testing TUI for PostgreSQL and MySQL.

Features

• TUI Dashboard: Real-time metrics visualization using Rich.
• Drift Correction: Load generation algorithm ensures accurate operations-per-second (OPS) targeting by accounting for query execution time.
• Dual-Database Support: Run tests against PostgreSQL and MySQL simultaneously or individually.
• Workload Simulation: Simulates a mixed workload of INSERT (30%), UPDATE (30%), SELECT (35%), and DELETE (5%) operations on a relational schema (Users -> Orders -> Items).
• Interactive Controls: Pause and resume specific loaders from the dashboard.

Quick Start

Prerequisites

• Docker
• uv (recommended)

1. Start Databases

Start the test instances using Docker Compose:

docker-compose up -d

2. Configure Environment

cp .env.example .env

Note: The default configuration works with the provided docker-compose setup.

3. Run the Load Test

Install dependencies and start the tool:

uv sync
uv run sql-stress

Usage

CLI Options

usage: sql-stress [-h] [--ops OPS] [--duration DURATION] [--db {postgres,mysql,both}] [--reset]

options:
  -h, --help            show this help message and exit
  --ops OPS             Operations per second for each database (default: 10)
  --duration DURATION   Duration in seconds (default: run indefinitely)
  --db {postgres,mysql,both}
                        Which database to load (default: both)
  --reset               Reset (truncate) load-test tables before seeding

Examples:

# 50 ops/sec on Postgres only
uv run sql-stress --ops 50 --db postgres

# Run for 30 seconds with a fresh database
uv run sql-stress --ops 100 --duration 30 --reset

Dashboard Controls

Key	Action
p	Pause/Resume PostgreSQL loader
m	Pause/Resume MySQL loader
q	Quit the application
Ctrl+C	Force Quit

Configuration

Database connection settings can be overridden via environment variables:

Variable	Default	Description
POSTGRES_HOST	localhost	PostgreSQL host
POSTGRES_PORT	5432	PostgreSQL port
POSTGRES_USER	postgres	User for PG connection
MYSQL_HOST	localhost	MySQL host
MYSQL_PORT	3306	MySQL port
MYSQL_USER	mysql	User for MySQL connection

See .env.example for the full list of variables.

Architecture

SQL Stress uses a threaded architecture to maintain UI responsiveness while generating load.

• AbstractLoader: A unified base class handles the run loop.
• Drift Correction: The loader calculates the exact wake-up time based on the execution duration of the previous query, ensuring the target OPS rate is met regardless of database latency (within saturation limits).