Stressgres

Stressgres is a stress-testing tool for ParadeDB and standard PostgreSQL, featuring both a text UI and an automated headless mode. We use it for local development and in CI to replicate and test against representative customer workloads, called suites.

Quickstart

  • Run the interactive UI against a suite:
cargo run -p stressgres -- ui stressgres/suites/single-node-planner-paths.toml
  • Run headless mode with logging:
cargo run -p stressgres -- headless stressgres/suites/single-node-planner-paths.toml --runtime=300000 --log-file=logs/test.log
  • Run headless mode tolerating transient database faults (e.g. under Antithesis)
cargo run -p stressgres -- headless stressgres/suites/single-node-planner-paths.toml --runtime=300000 --reconnect-grace=30000
  • Run a suite against a throwaway Postgres cluster built from a given pg_config:
cargo run -p stressgres -- auto /path/to/pg_config stressgres/suites/single-node-planner-paths.toml /tmp/stressgres-data --runtime 300000

Suites are TOML files in stressgres/suites/. Each suite describes a planner workload or PostgreSQL topology exercised by Stressgres.

A job can verify its query plan once whenever Stressgres opens a connection. Use a string for one required fragment or an array when several nodes must be present; the checks are case-insensitive and run after on_connect settings:

[[jobs]]
on_connect = "SET max_parallel_workers_per_gather = 0"
sql = "SELECT id FROM test WHERE message ||| 'beer' LIMIT 10"
sql_plan_contains = ["TopKScanExecState", "Custom Scan"]

Docker

To run Stressgres from within Docker, use:

docker run --rm paradedb/stressgres:latest /symbols/stressgres headless stressgres/suites/single-node-planner-paths.toml

The source, including all suites, is included in the Docker image. The image prebuilds Stressgres at /symbols/stressgres and can run in air-gapped environments like Antithesis.

For an interactive shell:

docker run -d --name stressgres paradedb/stressgres:latest
docker exec -it stressgres bash

Docker Hub

To publish the Stressgres image to Docker Hub, trigger a workflow dispatch of Publish Stressgres (Docker) from the Actions tab. This is useful to get updated Stressgres binaries to our BYOC end-to-end testing framework.

Antithesis

Antithesis is a deterministic simulation testing (DST) tool. Stressgres runs inside Antithesis through the Docker image. Each suite has a first_<suite>.sh setup script under stressgres/suites/antithesis/; the shared singleton_driver_stressgres.sh then runs the selected workload under fault injection. For more information on Antithesis test commands, see the Antithesis documentation.

To add a new suite:

  • Create the corresponding first_<suite>.sh setup script.

  • Trigger a release of the Docker image to the Antithesis registry via the Test pg_search (Antithesis) workflow. This workflow builds and publishes the latest commit ParadeDB and Stressgres Docker images to Antithesis, and triggers a test run.

If it behaves as desired, merge your new singleton driver to main. The new suite will then be added to the nightly Antithesis runs.

Connection Strings

To facilitate testing with Antithesis, we deploy the ParadeDB CloudNativePG cluster with a manifest that hardcodes a dummy password. This ensures we can modify the Stressgres suite connection_string without needing to extract passwords dynamically.

The manifests can be found at docker/manifests/antithesis-paradedb.yaml in paradedb/paradedb/paradedb/paradedb-enterprise and the password used in the singleton driver files must match.