Introduction
CockroachDB Workload is an easy-to-use command line tool for generating load against CockroachDB.
It includes the following workloads:
ledger - Financial ledger use case using the double-entry principle
order - Purchase orders as part of an e-commerce use case
outbox - Simulates the transactional outbox and inbox patterns
This tool provides an interactive shell for running workloads and monitoring progress and performance. Each workload has an init command to set up the test fixture and one or more run commands to execute the actual workload for a given period of time.
Source Code
The source code for the workload tool can be found on GitHub.
Project Setup
The project is packaged as a single executable JAR file and runs on any platform for which there is a Java 17+ (LTS) runtime.
Prerequisites
CockroachDB, with a trial enterprise license.
Linux / macOS
Java 17
Maven 3+ (optional, embedded wrapper available)
Setup CockroachDB
Create a local cluster of at least three nodes:
cockroach start --port=26257 --http-port=8080 --advertise-addr=localhost:26257 --join=localhost:26257 --insecure --store=datafiles/n1 --background
cockroach start --port=26258 --http-port=8081 --advertise-addr=localhost:26258 --join=localhost:26257 --insecure --store=datafiles/n2 --background
cockroach start --port=26259 --http-port=8082 --advertise-addr=localhost:26259 --join=localhost:26257 --insecure --store=datafiles/n3 --background
cockroach init --insecure --host=localhost:26257
Next, set up a database called workload:
cockroach sql --insecure --host=localhost:26257 -e "CREATE database workload"
Setup Workload
Install the JDK
Install the JDK (Ubuntu example):
sudo apt-get install openjdk-17-jdk
Confirm the installation by running:
java --version
Clone the project
git clone git@github.com:cockroachlabs-field/cockroachdb-workload.git
cd cockroachdb-workload
Build the executable jar
chmod +x mvnw
./mvnw clean install
Usage
Start the shell with:
java -jar target/workload.jar --help
Type help for additional CLI guidance.
Ledger Workload
The Ledger workload demonstrates a simple financial accounting system using the double-entry bookkeeping principle. The concept is to move funds between accounts using balanced, multi-legged transactions at a high frequency. As a financial system, it will conserve money at all times and provide an audit trail for all transactions performed towards the accounts.
Start the workload shell with:
java -jar target/workload.jar ledger
Then initialize the workload by creating an account plan:
init --help
The commands can run concurrently. The "transfer" command will move funds between random accounts and the "balance" command will just read account balances.
transfer --help
Hint: The ledger workload is implemented using both plain JDBC and JPA with Hibernate as ORM provider. You can switch between these implementations using the --jpa option (where JDBC is default).
Order Workload
The Order workload is a basic purchase order creation and reading workload. Order creation and reading workloads can run concurrently.
Start the workload with:
java -jar target/workload.jar order
init
run
Outbox Workload
The Outbox workload simulates the transactional outbox and inbox design patterns. It writes event records to an outbox table that has TTL and CDC enabled (optional). It can be used to evaluate creating a CDC-based data pipeline and/or the TTL mechanism.
Start the workload with:
java -jar target/workload.jar outbox
init
run
Extending
It's fairly simple to extend this tool with additional workloads. There are skeleton beans available in the "io.cockroachdb.workload.template" namespace that can be copied to a new workload package.
The main steps include:
Conclusion
In this article, we looked at a simple workload tool for CockroachDB using the Java stack. It can be used to send semi-realistic SQL traffic for pure testing and load-testing purposes. It's also quite extendable.
