tpcc

package
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, Apache-2.0 Imports: 21 Imported by: 0

README

TPC-C workload

TPC-C (spec §§2–3) with deterministic plain-Go population data and the standard 45/43/4/4/4 New-Order, Payment, Order-Status, Delivery, and Stock-Level mix. Eight tables are loaded through Bench.Insert; history starts empty and is populated by transactions.

Variants

  • tpcc/tx runs ordered DML in driver transactions on PostgreSQL, MySQL, and YDB, and as a non-transactional approximation on Picodata 26.2 or newer.
  • tpcc/procs sends one atomic routine invocation per operation. PostgreSQL, YugabyteDB, and supported CockroachDB dialects use functions; MySQL procedures own transaction start, commit, and rollback. Atomic MySQL procedure names end in _atomic; run --steps create_procedures to install them before reusing a dataset from an older binary. Old names cannot silently bypass transaction boundaries. Custom procedure SQL must own the same lifecycle.

Run it

./build/stroppy run tpcc/tx -d pg \
  -D url=postgres://postgres:postgres@localhost:5432/stroppy
./build/stroppy run tpcc/tx -d mysql \
  -D 'url=root:pass@tcp(127.0.0.1:3306)/stroppy'
./build/stroppy run tpcc/tx -d pico
./build/stroppy run tpcc/tx -d ydb -D url=grpc://localhost:2136/local
./build/stroppy run tpcc/procs -d pg

Typed workload parameters are listed by stroppy run tpcc/tx --help and stroppy run tpcc/procs --help:

  • --scale-factor sets the warehouse count.
  • --spread-warehouses chooses a home warehouse uniformly for each transaction instead of pinning each VU to one warehouse. The choice stays fixed across retries; this stress mode is not fixed-terminal TPC-C.
  • --warehouse-start sets the first warehouse ID for a distributed slice.
  • --load-items controls loading the shared 100,000-row item table; it defaults to true only when warehouse-start is 1.
  • --load-workers sets the workers used to load each table.
  • --pacing applies the TPC-C keying and think times.
  • --warmup adds traffic before the measured workload step (default 0s, constant-vus only); --duration remains the measured workload duration.
  • --retry-attempts sets the maximum transaction attempts.
  • --pg-unlogged uses PostgreSQL unlogged tables during the load.
  • --tx-isolation overrides the driver-specific isolation default.
  • --sql-file overrides the dialect SQL file.

YDB setup

Warehouse-keyed tables start with explicit warehouse split boundaries and keep that partition floor, while allowing automatic splitting beyond it. Item, history, and index tables use database partition-count defaults with size/load partitioning enabled. A row-table minimum prevents merges; it does not allocate that many partitions initially. Deployment-specific tuning belongs in an explicit SQL override rather than a fixed hardware assumption in the built-in schema.

Synchronous indexes are built after native loading: YDB BulkUpsert does not support tables with synchronous secondary indexes. Index consistency and loading order are unchanged. Setup errors include the failed statement's name/position, driver, elapsed time, and original backend error.

These defaults are locally verified on YDB 26.2; they are not a verified fix for managed serverless compilation timeouts. Managed schema-operation and request-unit quotas still apply. Serverless deployment capabilities must be checked separately.

Picodata approximation

Picodata execution uses isolation none, not a transaction spanning the operation's statements. It is a stress workload, not compliant TPC-C, and logs this limitation when execution starts. Picodata 26.2 or newer is required for the single-bucket atomic block that reads and increments the district's next order ID in one request; concurrent clients cannot reserve the same ID.

The rest of each operation remains non-transactional. A later failure can leave partial writes and unused order IDs; stock read/update sequences and other multi-statement operations are not isolated. The expected invalid-item rollback is disabled. Duplicate-key errors are terminal for the iteration, not a reason to retry partially applied writes. Reusing an inconsistent dataset is not repaired by atomic ID reservation.

Distributed warehouse ranges

Several processes can load disjoint warehouse ranges into one database:

# Creates the schema and loads warehouses 1..100 plus the shared item table.
./build/stroppy run tpcc/tx -d pg -D url=postgres://host/db \
  --warehouse-start 1 --scale-factor 100 \
  --steps drop_schema,create_schema,load_data,validate_population

# Loads warehouses 101..200 and leaves the shared item table alone.
./build/stroppy run tpcc/tx -d pg -D url=postgres://host/db \
  --warehouse-start 101 --scale-factor 100 \
  --steps load_data,validate_population

By default, each virtual user is pinned to a home warehouse within its configured slice. With --spread-warehouses, every transaction chooses a home warehouse from the full slice, so a small VU count can exercise a large warehouse range. Remote warehouse choices stay inside that slice and exclude the current home warehouse. On YDB, run create_schema once with the total warehouse range so generated partition keys cover every loader. Population validation is restricted to the configured slice.

Setup and execution

Setup runs these gatable steps in order:

  1. drop_schema
  2. create_schema, including Go-rendered YDB partition keys
  3. create_procedures for tpcc/procs only
  4. set_unlogged when requested on PostgreSQL
  5. load_data, using typed driver.InsertRequest values backed by gen.IndexedSource batches for warehouse, district, customer, item, stock, orders, order_line, and new_order
  6. create_indexes
  7. set_logged when unlogged loading was enabled
  8. create_foreign_keys
  9. analyze
  10. validate_population

Each workload iteration selects one transaction according to the standard mix. The tx variant executes its ordered statements within a driver transaction; the procs variant performs one procedure call. Both variants share retry policy, pacing, transaction metrics, and the final compliance report.

ydb.sql uses pre-split tablets and post-load indexes. To compare its load path with the single-tablet ydb_no_indexes.sql schema:

stroppy run tpcc/tx tpcc/ydb_no_indexes -d ydb -D url=grpc://host:2136/db \
  --scale-factor 50 --load-workers 8 \
  --steps drop_schema,create_schema,load_data
stroppy run tpcc/tx tpcc/ydb -d ydb -D url=grpc://host:2136/db \
  --scale-factor 50 --load-workers 8 \
  --steps drop_schema,create_schema,load_data,create_indexes

Run shapes and two-pass runs

./build/stroppy run tpcc/tx --executor shared-iterations --vus 4 --iterations 100
./build/stroppy run tpcc/tx --executor constant-vus --vus 64 --duration 1h

# Load first, then measure the existing data.
./build/stroppy run tpcc/tx --scale-factor 10 --no-steps workload
./build/stroppy run tpcc/tx --executor constant-vus --vus 64 --duration 1h \
  --steps workload

A normal run with no step filter performs setup and measurement together.

Warmup, pacing, and measurements

# Reuse loaded data, warm up for five minutes, then measure for thirty minutes.
./build/stroppy run tpcc/procs -d pg -D url=postgres://host/db \
  --executor constant-vus --vus 10000 --pacing=true \
  --warmup 5m --duration 30m --steps warmup,workload

Warmup uses the same transaction mix, worker RNG state, and history ID counter as measurement. Both phases export the existing metric names, distinguished by step=warmup and step=workload. The TPC-C report selects only workload histograms and its measurement window. Duration histograms also carry phase=warmup|measurement|drain and outcome=success|error|canceled, based on operation completion. TPC-C throughput counts successful completions during measurement; drain completions and cancellations are reported separately. Latency and transaction mix include failed measured operations. Generic summaries retain both phases and drain; filter exported series by step and phase when comparing measured traffic. Step filters apply normally: --steps workload excludes warmup even when --warmup is set. Each phase uses the configured drain policy, so elapsed time can exceed warmup plus duration. Workers activate immediately at each phase boundary; warmup alone does not guarantee steady state.

Keying waits precede database work. Think time follows each successful or nonfatal failed logical transaction, once after all retries. Fatal errors and cancellation stop immediately. Both waits observe cancellation; canceling post-transaction thinking does not turn an already successful transaction into a failure. Native success counters update before thinking, while native TPS still uses the executor wall-clock window, including drain.

Latency measures have different scopes:

  • tpcc_<transaction>_duration: logical database operation, including pool acquisition, retries, and failed outcomes; excludes keying and thinking.
  • tx_total_duration: one database transaction attempt, not the full retry loop.
  • iteration_duration: entire iteration, including keying, retries, and thinking.

At the first traffic iteration, history IDs start above the table's current maximum and are unique across workers and phases. Sequential runs can reuse a dataset without truncating history. Concurrent independent transaction processes must not share that history ID space: maximum-based initialization does not reserve ranges across processes. Distributed loading of disjoint warehouse ranges remains supported.

Pacing is a TPC-C-style stress profile, not an audited TPC-C result. Strict terminal/district and deferred Delivery semantics are tracked in #193; reusable gradual worker activation is tracked in #194. Environment variables and -e remain compatibility inputs; direct flags and typed config are preferred.

Integration test

make tmpfs-up
make build
go test -tags=integration -count=1 -run TestTpccWorkloadEndToEnd ./test/integration
make tmpfs-down
CockroachDB SQL

Use -d crdb for CockroachDB; it selects the built-in crdb.sql. For CockroachDB 24.1, add --sql-dialect crdb24; its procedures use WHILE loops supported by that version. --sql-dialect selects a built-in TPC-C asset without consulting local files. --sql-file remains an explicit filesystem path; the two selectors cannot be combined. Both variants retain the expected TPC-C rollback and use Cockroach-compatible decimal arithmetic and statistics. The cloud compiler selects the variant from the catalog database version. These SQL variants ignore --pg-unlogged: loading keeps CockroachDB's normal durability and does not issue PostgreSQL-only SET UNLOGGED/SET LOGGED commands.

Documentation

Overview

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 owns Stroppy's TPC-C implementation, tests, and dialect SQL. It runs five transactions as ordered DML steps inside driver transactions, with 45/43/4/4/4 mix, full population, and §1.3.1 validation. PostgreSQL, MySQL, Picodata, and YDB dialect branches are supported.

Index

Constants

This section is empty.

Variables

View Source
var (
	Tx    = bench.Test{Name: "tpcc/tx", Define: defineTx, Source: publication("Tx")}
	Procs = bench.Test{Name: "tpcc/procs", Define: defineProcs, Source: publication("Procs")}
)

Functions

This section is empty.

Types

type Report

type Report struct {
	Workload             string      `json:"workload"`
	Paced                bool        `json:"paced"`
	SpreadWarehouses     bool        `json:"spread_warehouses,omitempty"`
	NonTransactional     bool        `json:"non_transactional,omitempty"`
	ComplianceApplicable bool        `json:"compliance_applicable"`
	ElapsedSeconds       float64     `json:"elapsed_seconds"`
	WarmupSeconds        float64     `json:"warmup_seconds,omitempty"`
	DrainSeconds         float64     `json:"drain_seconds,omitempty"`
	TpmC                 float64     `json:"tpm_c"`
	MixCompliant         *bool       `json:"mix_compliant"`
	ResponseCompliant    *bool       `json:"response_compliant"`
	MixTolerancePct      float64     `json:"mix_tolerance_pct"`
	Transactions         []TxReport  `json:"transactions"`
	Statistical          Statistical `json:"statistical"`
	Steadiness           Steadiness  `json:"steadiness"`
	Note                 string      `json:"note,omitempty"`
}

Report is the machine-readable TPC-C compliance report. Verdict fields that do not apply to the run (unpaced) are nil.

type Statistical

type Statistical struct {
	TotalMeasurements uint64 `json:"total_measurements"`
	NewOrders         uint64 `json:"new_orders"`
	Sufficient        bool   `json:"sufficient"`
	Reason            string `json:"reason,omitempty"`
}

Statistical reports whether the run observed enough data to support a compliance claim, and why not when it is insufficient.

type Steadiness

type Steadiness struct {
	Status    string  `json:"status"` // "pass", "fail", "insufficient", "not_assessed"
	CV        float64 `json:"cv"`
	Mean      float64 `json:"mean_new_orders_per_sec"`
	Sigma     float64 `json:"sigma_new_orders_per_sec"`
	Buckets   int     `json:"buckets"`
	Truncated bool    `json:"truncated"`
	Reason    string  `json:"reason,omitempty"`
}

Steadiness is the 3σ steady-state check: the coefficient of variation (CV) of per-window New-Order throughput over the measurement window. Mean and Sigma are New-Orders-per-second; CV = Sigma/Mean.

type TxReport

type TxReport struct {
	Name             string   `json:"name"`
	Count            uint64   `json:"count"`
	Successful       uint64   `json:"successful"`
	Failed           uint64   `json:"failed"`
	Canceled         uint64   `json:"canceled"`
	Drained          uint64   `json:"drained"`
	MixPercent       float64  `json:"mix_percent"`
	ThroughputPerSec float64  `json:"throughput_per_sec"`
	P50Ms            float64  `json:"p50_ms"`
	P90Ms            float64  `json:"p90_ms"`
	P95Ms            float64  `json:"p95_ms"`
	P99Ms            float64  `json:"p99_ms"`
	CeilingMs        *float64 `json:"ceiling_ms"`
	MixMinPercent    *float64 `json:"mix_min_percent"`
	MixPass          *bool    `json:"mix_pass"`
	ResponsePass     *bool    `json:"response_pass"`
}

TxReport is the per-transaction-type observation and, when applicable, its verdict against the §5.2.2 mix minimum (with the tolerance already applied) and the §5.2.5 response-time ceiling.

Directories

Path Synopsis
published
workloadtest
Package workloadtest provides contract assertions for embedded workload assets.
Package workloadtest provides contract assertions for embedded workload assets.

Jump to

Keyboard shortcuts

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