stroppy

package module
v6.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

Stroppy

Discord Docs

Database stress testing CLI. A single self-contained Go binary with no external runtime dependencies.

Features

  • Built-in TPC-B, TPC-C, TPC-H, and TPC-DS workload tests
  • Deterministic typed Go generation and loading through driver.InsertRequest
  • PostgreSQL, MySQL, YDB, Picodata, CSV, and noop drivers
  • Transaction support with configurable isolation levels
  • Go-native load generation and metrics
  • Opt-in Go profiling for CLI and SDK runs with --pprof or STROPPY_PPROF

Installation

Pre-built Binaries

Download the latest release from GitHub Releases.

Docker
docker pull ghcr.io/stroppy-io/stroppy:latest
# or build locally
docker build -t stroppy .
Build from Source

Build requirements: Go 1.24.3+

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

The first argument selects a built-in workload; the optional second is a .sql schema file override. Inline SQL is also accepted:

stroppy run tpcc/tx           # TPC-C, raw transactions (any DB)
stroppy run tpcc/procs        # TPC-C, 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 --scale-factor 1   # TPC-DS, load 24 tables + 99 queries
stroppy run queries.sql       # execute a SQL file
stroppy run "select 1"        # execute inline SQL

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

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

TPC-H loads all eight tables and runs the 22 query suite. TPC-DS generates and loads all 24 tables (faithful dsdgen port) and runs the 99 query suite; scale either workload via --scale-factor.

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

stroppy run tpcc/tx -d pg
stroppy run tpcc/tx -d mysql -D 'url=root:pass@tcp(localhost:3306)/bench'
stroppy run tpcc/tx -d pico
stroppy run simple -d noop                  # framework/runner overhead only

Registered workloads expose typed direct flags. Select the executor explicitly; use stroppy run <workload> --help to inspect that workload's parameters:

stroppy run tpcc/tx --executor constant-vus --vus 10 --duration 60s
stroppy run tpcc/tx --executor shared-iterations --iterations 100
stroppy run tpcc/tx --scale-factor 10 --load-workers 8
stroppy run tpcc/tx -D pool.maxConns=200

Collect repeated settings in stroppy-config.json or an explicit -f file. Typed scenario parameters belong under run, workload parameters under params. Driver configuration uses names, with "default" for the default database:

{
  "version": "1",
  "script": "tpcc/tx",
  "run": {"executor": "constant-vus", "vus": 10, "duration": "60s"},
  "params": {"scaleFactor": 10, "loadWorkers": 8}
}
stroppy run -f prod.json

Typed parameter precedence is: CLI flag > process environment > matching run/params config > declared default. Driver precedence is -d/-D > config drivers. -e, config env, numeric driver suffixes, and duration-based executor inference are removed. Named multi-driver workloads use -dprimary/-Dprimary.

Custom Go workloads use the supported authoring API and standalone application shell. Runnable examples cover queries, loading, transactions, telemetry, reports, and named databases. Author tooling covers stroppy init, ordinary noop/recording tests, and safe stroppy eject of explicitly published workload sources.

Every workload can emit one versioned JSON report containing effective inputs, host details, steps, metrics, bounded errors, and workload-specific results:

stroppy run tpcb/tx -d pg --report-format json
stroppy run tpcc/tx -d pg --report-file result.json

Human output and diagnostics remain on stderr, so requested stdout stays valid JSON. See run reports for report fields, output behavior, and workload payloads.

Custom Go workloads can run as self-contained applications, join the local catalog, and export with built-ins into one portable binary. See standalone workloads.

Use stroppy help to explore available topics:

stroppy help drivers
stroppy help config-file
Probe

Probe lists registered workload parameter schemas, embedded presets, and the insert methods each driver supports:

stroppy probe
stroppy probe -o json
Workload Tree
├─ execute_sql            (run a .sql file or inline SQL)
├─ simple                 (smoke / overhead benchmark)
├─ tpcb
│  ├─ tx                  (raw transactions — any DB)
│  └─ pg.sql crdb.sql mysql.sql tidb.sql pico.sql ydb.sql
├─ tpcc
│  ├─ tx                  (raw transactions — any DB)
│  ├─ procs               (stored procedures — pg/mysql)
│  └─ pg.sql crdb.sql mysql.sql pico.sql ydb.sql ydb_no_indexes.sql
├─ tpch
│  ├─ tx                  (relational load + 22 queries)
│  └─ pg.sql crdb.sql mysql.sql pico.sql ydb.sql distributions.json answers_sf1.json
└─ tpcds
   ├─ tpcds               (load 24 tables + 99 queries)
   └─ schema.pg.sql schema.mysql.sql schema.pico.sql schema.ydb.sql \
        pg.sql mysql.sql pico.sql ydb.sql answers_sf1.json

Docker Usage

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

docker run --network host ghcr.io/stroppy-io/stroppy run simple
docker run --network host stroppy run tpcc/tx \
  -d pg -D url=postgres://user:password@host:5432/dbname

Available workloads: simple, tpcb/tx, tpcc/tx, tpch/tx, tpcds, execute_sql.

Native metrics and throughput

Stroppy exports the workload's counters, bounded latency histograms, load progress, error classes and retries through OTLP. TPC-C also retains its compliance report. Each invocation has a unique metric writer identity, and configured run metadata is preserved on exported points so parallel runs and segments can be filtered.

  • tps: successful logical transactions per second for TPC-B/TPC-C and baseline. Retries count once when successful; a workload-defined expected rollback counts as a successful logical operation. This is separate from TPC-C tpmC.
  • iterations_per_second: completed iterations, including failed iterations.
  • queries_per_second: successful SDK queries during the executor window.
  • measurement_seconds: elapsed executor wall time shared across VUs, excluding setup and teardown; successful_transactions_total supplies the TPS numerator.

Rates are cumulative averages during execution and freeze when the executor ends. Skipped transaction steps do not publish TPS. Nontransactional workloads expose their own operation and iteration measurements. Prometheus-compatible receivers may normalize OTLP names and append unit suffixes (for example stroppy_tps_per_second).

License

See LICENSE file for details.

Documentation

Overview

Package stroppy turns one test definition into a standalone Stroppy application.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Main

func Main(test bench.Test)

Main runs one workload as a standalone process with Stroppy signal semantics.

func RegisteredMain

func RegisteredMain(identity ...string)

RegisteredMain runs every workload registered through bench.Register. Generated portable Stroppy binaries use this entrypoint after blank-importing built-in and selected custom workload packages.

Types

type Application

type Application struct {
	// contains filtered or unexported fields
}

Application is one standalone Stroppy workload.

func New

func New(test bench.Test) (*Application, error)

New validates a Test and creates a standalone application.

func NewCatalog

func NewCatalog(catalog *bench.Catalog) (*Application, error)

NewCatalog creates an application over an explicit catalog without global registration.

func (*Application) Execute

func (a *Application) Execute(
	ctx context.Context,
	args []string,
	stdout, stderr io.Writer,
) error

Execute runs standalone command behavior without exiting host process.

func (*Application) Name

func (a *Application) Name() string

Name returns standalone workload identity.

func (*Application) Run

func (a *Application) Run(ctx context.Context, request *RunRequest) (*report.Run, error)

Run returns report data without automatic filesystem persistence.

type RunRequest

type RunRequest struct {
	Test          string
	Drivers       map[string]bench.DriverConfig
	Params        bench.ParamInputs
	Steps         []string
	NoSteps       []string
	Logger        bench.Logger
	Metrics       *bench.MetricsConfig
	ReportOptions bench.ReportOptions
	NoReport      bool
	Capture       *bench.CaptureOptions
	Profiling     *profiling.Config
}

RunRequest contains programmatic inputs for one workload run.

Directories

Path Synopsis
cmd
dstparse command
dstparse transforms TPC-DS dsdgen `.dst` distribution files into the uniform Dict-shaped JSON document consumed by the relations data generator.
dstparse transforms TPC-DS dsdgen `.dst` distribution files into the uniform Dict-shaped JSON document consumed by the relations data generator.
stroppy command
stroppy/commands/baseline
Package baseline implements `stroppy baseline`: it measures stroppy's own overhead on the current machine — the noop-driver framework ceiling and the pg-wire protocol ceiling against a pg-noop blackhole server — and saves a versioned report for future comparison.
Package baseline implements `stroppy baseline`: it measures stroppy's own overhead on the current machine — the noop-driver framework ceiling and the pg-wire protocol ceiling against a pg-noop blackhole server — and saves a versioned report for future comparison.
stroppy/commands/help
Package help implements the `stroppy help <topic>` subcommand.
Package help implements the `stroppy help <topic>` subcommand.
stroppy/commands/probe
Package probe lists embedded workload presets and driver capabilities.
Package probe lists embedded workload presets and driver capabilities.
tpcds-answers command
tpcds-answers parses the official TPC-DS kit reference answer sets (`answer_sets/*.ans`) into a single `answers_sf1.json` document keyed by the query-statement names used in the baked per-dialect SQL (`query_1` … `query_99`, with the two-part queries 14/23/24/39 split into `_a`/`_b`).
tpcds-answers parses the official TPC-DS kit reference answer sets (`answer_sets/*.ans`) into a single `answers_sf1.json` document keyed by the query-statement names used in the baked per-dialect SQL (`query_1` … `query_99`, with the two-part queries 14/23/24/39 split into `_a`/`_b`).
tpcds-diff command
tpcds-diff compares two TPC-DS query-result dumps produced by the workload's ANSWER_DUMP mode (lines "__TPCDS_DUMP__\t<name>\t<json-rows|ERR:msg>" in a run log).
tpcds-diff compares two TPC-DS query-result dumps produced by the workload's ANSWER_DUMP mode (lines "__TPCDS_DUMP__\t<name>\t<json-rows|ERR:msg>" in a run log).
tpch-answers command
tpch-answers parses a directory of TPC-H reference answer files into a single `answers_sf1.json` document.
tpch-answers parses a directory of TPC-H reference answer files into a single `answers_sf1.json` document.
tpch-dists command
tpch-dists transforms upstream TPC-H `dists.dss` into the uniform Dict-shaped JSON document consumed by the relations data generator.
tpch-dists transforms upstream TPC-H `dists.dss` into the uniform Dict-shaped JSON document consumed by the relations data generator.
examples
authoring
Package authoring contains small workloads using only the supported author API.
Package authoring contains small workloads using only the supported author API.
authoring/main command
internal
author
Package author scaffolds standalone projects from explicitly published workload files.
Package author scaffolds standalone projects from explicitly published workload files.
author/generate command
Command generate refreshes explicitly published builtin source support files.
Command generate refreshes explicitly published builtin source support files.
capture
Package capture writes bounded run recordings independently of database work.
Package capture writes bounded run recordings independently of database work.
cli
Package cli assembles Stroppy's reusable command interface.
Package cli assembles Stroppy's reusable command interface.
jsonschema-gen command
Command jsonschema-gen emits the JSON Schema for pkg/config's file envelope.
Command jsonschema-gen emits the JSON Schema for pkg/config's file envelope.
pgnoop
Package pgnoop manages the external pg-noop blackhole server binary used by the baseline command: resolving it from an embedded copy, the local cache, or the pinned GitHub release, and running it for the duration of a run.
Package pgnoop manages the external pg-noop blackhole server binary used by the baseline command: resolving it from an embedded copy, the local cache, or the pinned GitHub release, and running it for the duration of a run.
rowmap
Package rowmap shares shallow SQL-row conversion with ordinary struct sources.
Package rowmap shares shallow SQL-row conversion with ordinary struct sources.
testdriver
Package testdriver scopes database-free backend selection to one test run.
Package testdriver scopes database-free backend selection to one test run.
toolchain
Package toolchain resolves system or Stroppy-owned Go compilers.
Package toolchain resolves system or Stroppy-owned Go compilers.
workloadcatalog
Package workloadcatalog stores compiled custom workloads owned by Stroppy.
Package workloadcatalog stores compiled custom workloads owned by Stroppy.
pkg
bench/mpp
Package mpp is what the analytical workloads share about Greenplum-family engines (Greenplum, Greengage, WarehousePG, Apache Cloudberry): the dialect name and the check that keeps a run on the dialect that matches the server it is connected to.
Package mpp is what the analytical workloads share about Greenplum-family engines (Greenplum, Greengage, WarehousePG, Apache Cloudberry): the dialect name and the check that keeps a run on the dialect that matches the server it is connected to.
bench/testkit
Package testkit runs ordinary workloads without a database or report history.
Package testkit runs ordinary workloads without a database or report history.
config
Package config holds the plain-Go application configuration types for run, workload, driver, pool, logger, exporter, and isolation settings.
Package config holds the plain-Go application configuration types for run, workload, driver, pool, logger, exporter, and isolation settings.
datagen/source
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
driver/common
Package common hosts driver-agnostic building blocks shared by every Stroppy database driver.
Package common hosts driver-agnostic building blocks shared by every Stroppy database driver.
driver/csv
Package csv implements an ephemeral Stroppy driver that writes generator output to CSV files on the local filesystem instead of a database.
Package csv implements an ephemeral Stroppy driver that writes generator output to CSV files on the local filesystem instead of a database.
driver/insertprogress
Package insertprogress provides driver-agnostic insert operation progress tracking.
Package insertprogress provides driver-agnostic insert operation progress tracking.
driver/noop
Package noop provides a no-op database driver that discards all operations without performing any I/O. It is intended for benchmarking stroppy's own framework overhead in isolation from actual database latency.
Package noop provides a no-op database driver that discards all operations without performing any I/O. It is intended for benchmarking stroppy's own framework overhead in isolation from actual database latency.
driver/recording
Package recording implements a database-free driver that records operations.
Package recording implements a database-free driver that records operations.
gen
Package gen provides deterministic data-generation primitives for stroppy workloads.
Package gen provides deterministic data-generation primitives for stroppy workloads.
profiling
Package profiling provides opt-in, process-wide Go diagnostics for Stroppy applications.
Package profiling provides opt-in, process-wide Go diagnostics for Stroppy applications.
record
Package record provides structured, deterministic operation recordings for workload tests.
Package record provides structured, deterministic operation recordings for workload tests.
report
Package report defines Stroppy's versioned machine-readable run report.
Package report defines Stroppy's versioned machine-readable run report.
report/compare
Package compare calculates explicit, dimension-preserving comparisons of saved runs.
Package compare calculates explicit, dimension-preserving comparisons of saved runs.
report/view
Package view renders saved run reports without changing their data.
Package view renders saved run reports without changing their data.
Package workloads provides workload-owned embedded SQL, JSON, and documentation files.
Package workloads provides workload-owned embedded SQL, JSON, and documentation files.
all
Package all registers every built-in workload through blank imports.
Package all registers every built-in workload through blank imports.
banking
Package banking is a bank-transfer invariant workload: every transfer must preserve the total balance and the token multiset, under concurrency and injected faults.
Package banking is a bank-transfer invariant workload: every transfer must preserve the total balance and the token multiset, under concurrency and injected faults.
banking/published/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
baseline
Package baseline provides Stroppy's machine-benchmark workload.
Package baseline provides Stroppy's machine-benchmark workload.
execute_sql
Package execute_sql runs named queries from inline or file SQL sources.
Package execute_sql runs named queries from inline or file SQL sources.
internal/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
simple
Package simple provides Stroppy's minimal workload example.
Package simple provides Stroppy's minimal workload example.
tpcb
Package tpcb owns Stroppy's TPC-B implementation, tests, and dialect SQL.
Package tpcb owns Stroppy's TPC-B implementation, tests, and dialect SQL.
tpcb/published/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
tpcc
Package tpcc implements the five TPC-C transactions as ordered DML steps inside driver transactions with the standard 45/43/4/4/4 mix.
Package tpcc implements the five TPC-C transactions as ordered DML steps inside driver transactions with the standard 45/43/4/4/4 mix.
tpcc/published/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
tpcds
Package tpcds owns Stroppy's TPC-DS implementation, tests, dialect SQL, and answer data.
Package tpcds owns Stroppy's TPC-DS implementation, tests, dialect SQL, and answer data.
tpcds/dsdgen
Package dsdgen is a spec-faithful Go port of the TPC-DS data generator (dsdgen, v4.0.0).
Package dsdgen is a spec-faithful Go port of the TPC-DS data generator (dsdgen, v4.0.0).
tpcds/dsqgen
Package dsqgen is a lean port of the TPC-DS query generator (dsqgen).
Package dsqgen is a lean port of the TPC-DS query generator (dsqgen).
tpcds/dsqgen/cmd/dsqgen command
Command dsqgen renders TPC-DS query streams for a target SQL dialect, drawing valid, scale-correct parameter values with a seeded RNG (it does not reproduce the C dsqgen's exact value stream).
Command dsqgen renders TPC-DS query streams for a target SQL dialect, drawing valid, scale-correct parameter values with a seeded RNG (it does not reproduce the C dsqgen's exact value stream).
tpcds/published/source
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
tpcds/published/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
tpcds/tpcdsgen
Package tpcdsgen adapts the ported TPC-DS dsdgen generator (third_party/gotpcds/dsdgen) to the source.Partitionable contract, so the spec-faithful, byte-exact generator feeds any Stroppy driver through the same load path as the native evaluator and the TPC-H generator.
Package tpcdsgen adapts the ported TPC-DS dsdgen generator (third_party/gotpcds/dsdgen) to the source.Partitionable contract, so the spec-faithful, byte-exact generator feeds any Stroppy driver through the same load path as the native evaluator and the TPC-H generator.
tpch
Package tpch owns Stroppy's TPC-H implementation, tests, dialect SQL, and answer data.
Package tpch owns Stroppy's TPC-H implementation, tests, dialect SQL, and answer data.
tpch/published/source
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
Package source defines the row-production contract that every load-time data generator implements and every driver consumes.
tpch/published/workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.
tpch/tpchgen
Package tpchgen adapts the vendored TPC-H dbgen generator (third_party/gotpc/dbgen) to the source.Partitionable contract so the ported, spec-faithful generator can feed any Stroppy driver through the same load path as the native evaluator.
Package tpchgen adapts the vendored TPC-H dbgen generator (third_party/gotpc/dbgen) to the source.Partitionable contract so the ported, spec-faithful generator can feed any Stroppy driver through the same load path as the native evaluator.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL