The runner connects to PostgreSQL, optionally initializes pgbench tables, and streams native pgbench results. It also writes structured summary metrics to the Kubernetes termination message file.
From the repository root:
docker build -t plugin-bench-pgbench:dev runners/pgbenchThe Go wrapper is built with Go 1.25, matching the backend and Sysbench runner. The runtime image remains PostgreSQL 16 on Alpine.
docker network create pgbench-test
docker run -d \
--name pgbench-db-test \
--network pgbench-test \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=pgbench \
postgres:16-alpine
ready=false
for attempt in {1..30}; do
if docker exec pgbench-db-test pg_isready -U postgres -d pgbench; then
ready=true
break
fi
sleep 1
done
if [ "$ready" != true ]; then
echo "PostgreSQL did not become ready"
exit 1
fiRequired connection variables:
PGHOST PostgreSQL hostname
PGDATABASE Database name
PGUSER PostgreSQL user
PGPASSWORD Password, or use PGPASSFILE
Optional connection variables include PGPORT (default 5432), PGCONNECT_TIMEOUT (default 10), PGSSLMODE, and PGSSLROOTCERT.
For PGPASSFILE, mount a password file readable by the container's postgres user, with mode 0600, and supply its container path. When set, PGPASSWORD takes precedence.
Benchmark variables:
BENCH_INITIALIZE Initialize tables; default false
BENCH_DURATION Duration in seconds; default 60
BENCH_CLIENTS Concurrent clients; default 1
BENCH_THREADS pgbench threads; default 1
BENCH_SCALE Initialization scale; default 1
BENCH_THREADS cannot exceed BENCH_CLIENTS.
Initialize the disposable database and run a 30-second benchmark. BENCH_INITIALIZE=true drops and recreates existing pgbench tables, so use it only with a disposable database:
docker run --rm \
--network pgbench-test \
-e PGHOST=pgbench-db-test \
-e PGPORT=5432 \
-e PGDATABASE=pgbench \
-e PGUSER=postgres \
-e PGPASSWORD=postgres \
-e BENCH_INITIALIZE=true \
-e BENCH_DURATION=30 \
-e BENCH_CLIENTS=2 \
-e BENCH_THREADS=2 \
plugin-bench-pgbench:devThe output includes tps, average latency, and failed transactions. Run again without BENCH_INITIALIZE to reuse the tables.
The runner passes connection settings through PostgreSQL environment variables and does not put credentials in command-line arguments. It returns a non-zero exit code for invalid configuration, connection failures, initialization failures, or benchmark failures.
After a successful benchmark, the runner extracts TPS (without initial connection time) and average latency from pgbench's final summary. It writes a versioned JSON record of at most 4 KiB to /dev/termination-log:
{"version":1,"metrics":[{"name":"tps","unit":"tx/s","value":1234.5},{"name":"latency_avg","unit":"ms","value":3.2}]}Kubernetes supplies this file; use terminationMessagePolicy: File on the runner container. Raw stdout and stderr continue to appear in the container logs. Initialization output is excluded from metrics, and subprocesses use LC_ALL=C for stable summary formatting.
When metrics are missing, malformed, or cannot be written, the runner emits a generic warning and preserves the benchmark exit status. A plain Docker invocation without a writable termination file therefore still works, but reports metrics as unavailable. Failed or cancelled benchmarks do not write a success record.
The backend reads the current runner container's termination message before cleanup and returns decoded metrics separately from logs. See the shared request and runner result contracts.
Docker does not supply Kubernetes' termination file. Against the disposable database above, mount a fresh writable file to inspect it. This example enables initialization and therefore recreates pgbench tables:
metrics_dir=$(mktemp -d)
trap 'rm -f "$metrics_dir/result.json"; rmdir "$metrics_dir"' EXIT
touch "$metrics_dir/result.json"
# The parent directory is private; allow the container's postgres user to write
# the single mounted file without assuming its numeric UID matches the host.
chmod 666 "$metrics_dir/result.json"
docker run --rm \
--network pgbench-test \
--mount "type=bind,src=$metrics_dir/result.json,dst=/dev/termination-log" \
-e PGHOST=pgbench-db-test -e PGDATABASE=pgbench -e PGUSER=postgres \
-e PGPASSWORD=postgres -e BENCH_INITIALIZE=true -e BENCH_DURATION=5 \
plugin-bench-pgbench:dev
cat "$metrics_dir/result.json"Use a fresh file for each invocation so a failed run cannot expose a previous run's success record. From the repository root, the automated image check is:
bash .github/scripts/test-runner.sh plugin-bench-pgbench:devIt requires Docker and Python 3, creates its own disposable PostgreSQL database, checks initialization and table reuse, compares metrics with the same run's log summary, and verifies authentication failure and cleanup.
docker rm -f pgbench-db-test
docker network rm pgbench-test