Stroppy

Database stress testing CLI tool powered by the k6 workload engine.

Features

• Built-in TPC-B, TPC-C, TPC-H, and TPC-DS-like workload tests
• Custom workload support in TypeScript
• Deterministic relational data generation with Rel.table and driver.insertSpec
• PostgreSQL, MySQL, YDB, Picodata, CSV, and noop drivers
• Transaction support with configurable isolation levels
• k6-based load generation, metrics, thresholds, and output integrations

Installation

Pre-built Binaries

Download the latest release from GitHub Releases.

Docker

docker pull ghcr.io/stroppy-io/stroppy:latest

docker build -t stroppy .

Build from Source

Build requirements: Go 1.24.3+

make install-xk6  # installs k6, used internally by stroppy
make build

The binary will be available at ./build/stroppy.

Quick Start

Configure the target database via driver flags:

stroppy run tpcc/tx -d pg -D url=postgres://user:password@host:5432/dbname

Run Tests

You can run a test from the local directory.

./stroppy run workloads/simple/simple.ts

Many tests are embedded in stroppy. The first argument is a .ts workload, the optional second is a .sql schema file. Extensions may be omitted.

TPC-B and TPC-C each ship two scripts:

• procs — uses stored procedures; supports PostgreSQL and MySQL
• tx — uses raw transactions; works with all SQL drivers (PostgreSQL, MySQL, Picodata, YDB)

TPC-H ships tpch/tx, a relational-framework workload that loads all eight tables and runs the 22 query suite. TPC-DS is available as a SQL-query workload.

stroppy run tpcc/procs        # TPC-C, stored procedures (pg/mysql)
stroppy run tpcc/procs.ts     # same, explicit extension
stroppy run tpcc/tx           # TPC-C, raw transactions (any DB)
stroppy run tpcb/procs        # TPC-B, stored procedures (pg/mysql)
stroppy run tpcb/tx           # TPC-B, raw transactions (any DB)
stroppy run tpch/tx           # TPC-H, relational load + query suite
stroppy run tpcds tpcds-scale-100  # TPC-DS-like SQL query set

And you can mix builtin tests with your own scripts or SQL files:

stroppy run tpcb/procs ./my-experimental.sql
stroppy run ./my-tpcb.ts tpcb/pg.sql

Use -d to select a driver preset and -D to override driver options:

stroppy run tpcc/procs -d pg
stroppy run tpcc/procs -d mysql -D url=mysql://root:pass@localhost:3306/bench
stroppy run tpcc/tx -d pico                   # picodata: use tx variant
stroppy run tpcc/procs -d pg -d1 mysql        # two drivers
stroppy run simple -d noop                    # framework/runner overhead only

Pass environment variables to the script with -e (keys are auto-uppercased):

stroppy run tpcc/tx -e pool_size=200
stroppy run tpcc/tx -d pg -e scale_factor=2
stroppy run tpcc/tx -d pg -e load_workers=8   # parallelize load_data InsertSpecs

Collect repeated settings in stroppy-config.json or an explicit -f file:

stroppy run -f prod.json
stroppy probe -f prod.json --envs --drivers

Precedence is: real environment > -e > config env > -d/-D > config drivers > script defaults.

Use stroppy help to explore available topics:

stroppy help drivers
stroppy help resolution
stroppy help datagen

Probe Tests

Probe inspects a workload and prints its configuration and SQL schema without running it.

stroppy probe tpcc/procs
stroppy probe tpcc/tx.ts

stroppy help probe

Presets Tree

├─ execute_sql
│  └─ execute_sql.ts
├─ simple
│  └─ simple.ts
├─ tests
│  └─ csv_smoke.ts multi_drivers_test.ts runtime_generators_api_test.ts
│     sqlapi_test.ts transaction_test.ts
├─ tpcb
│  ├─ procs.ts            (stored procedures — pg/mysql)
│  ├─ tx.ts               (raw transactions  — any DB)
│  └─ pg.sql mysql.sql pico.sql ydb.sql
├─ tpcc
│  ├─ procs.ts            (stored procedures — pg/mysql)
│  ├─ tx.ts               (raw transactions  — any DB)
│  └─ pg.sql mysql.sql pico.sql ydb.sql ydb_no_indexes.sql
├─ tpch
│  ├─ tx.ts               (relational load + 22 queries)
│  ├─ tpch_helpers.ts tpch_validate.ts
│  └─ pg.sql mysql.sql pico.sql ydb.sql distributions.json answers_sf1.json
└─ tpcds
   ├─ tpcds-scale-(1/10/100/300/1000/3000/10000/30000/50000/100000).sql
   └─ tpcds.ts

Generate Test Workspace

Generate workspace with preset:

stroppy gen --workdir mytest --preset=simple

Check available presets:

stroppy help gen

This creates a new directory with:

• Stroppy binary
• Test configuration files
• TypeScript test templates

Install dependencies:

cd mytest && npm install

Developing Test Scripts

After generating a workspace:

1. Edit TypeScript test files in your workdir
2. Import stroppy helpers and, for generated loads, datagen.ts.
3. Use k6 APIs for test scenarios
4. Run with ./stroppy run <test-file>.ts

Look at simple.ts, tpcb/tx.ts, and docs/datagen-framework.md first as references.

Docker Usage

Using Built-in Workloads

Run directly (--network host to reach localhost databases):

docker run --network host ghcr.io/stroppy-io/stroppy run simple

Add the tag to image:

docker tag ghcr.io/stroppy-io/stroppy stroppy

docker run --network host stroppy run tpcb/procs \
  -d pg -D url=postgres://user:password@host:5432/dbname

Available workloads: simple, tpcb, tpcc, tpch, tpcds, execute_sql

Create Persistent Workdir

# Generate workspace
docker run -v $(pwd):/workspace stroppy gen --workdir mytest --preset=simple
cd mytest

# Run test
docker run -v $(pwd):/workspace stroppy run simple.ts

Advanced Usage

Using as k6 Extension

Stroppy is built as a k6 extension. If you're familiar with k6, you can use the k6 binary directly to access all k6 features:

# Build both k6 and stroppy binaries
make build

# Use k6 binary directly with all k6 options
./build/k6 run --vus 10 --duration 30s test.ts

# Use k6 output options (JSON, InfluxDB, etc.)
./build/k6 run --out json=results.json test.ts

# All the stroppy commands accessible as extension
./build/k6 x stroppy run workloads/simple/simple.ts

The stroppy extensions are available via k6/x/stroppy module in your test scripts, giving you full access to both k6 and stroppy capabilities.

Contribution

Full Build With Generated Files

Build requirements: Go 1.24.3+, Node.js and npm, git, curl, unzip

make install-bin-deps
make proto            # build protobuf and ts framework bundle
make build

License

See LICENSE file for details.