Quickstart Guide & Core Architecture

What is ChaosSQL?

ChaosSQL is a Deterministic Concurrency and Invariant Fuzzer for SQL Databases, designed by Ricardo Bregalda (Studio Bregalda). In modern concurrent systems and distributed microservices architectures, concurrency anomalies such as Lost Updates, Write Skew, Dirty Reads and Deadlocks are notoriously elusive to reproduce, isolate, and debug. Traditional unit tests execute sequentially in isolation, whereas stochastic load-testing tools (such as JMeter or k6) inject uncontrollable scheduling noise that rarely hits the precise microsecond context switches required to trigger race conditions.

ChaosSQL bridges this fundamental gap by combining chaos engineering with three core pillars of theoretical computer science:

• Seeded Jitter Scheduling: The engine interleaves workers with delays drawn from a seeded PRNG, so the same spec and seed replay the same schedule. The transparent proxy adds a PCT-style scheduler inspired by Burckhardt & Musuvathi (ASPLOS 2010). Neither scheduler proves that a bug is absent; they make the schedules you explore reproducible.
• Automated Anomaly Classification via Adya Graphs: Reconstructs the Direct Serialization Graph (DSG) based on Atul Adya's MIT 1999 doctoral thesis and black-box verification techniques inspired by Elle (VLDB 2020), identifying rw (anti-dependency), ww (overwrite), and wr (read dependency) conflict edges.
• Delta-Debugging (ddmin): Implements Andreas Zeller's delta-debugging algorithm with memoized replays and a final 1-minimality audit, shrinking a failing trace to the smallest set of operations that still produces the same failure signature.

Core 4-Stage Architecture Pipeline

Every execution of ChaosSQL flows through a modular, deterministic four-stage processing pipeline:

1. Fuzzer (PCT-SQL Scheduler): Orchestrates concurrent worker goroutines with calibrated microsecond jitter and dynamic priority assignment, exploring non-linear execution schedules.
2. Detector (Adya Cycle & Invariant Engine): Evaluates data consistency assertions, inspects transactional histories, and constructs the Direct Serialization Graph (SG(S)) to identify anomalous cycles (rw, ww, wr).
3. Shrinker (Delta-Debugging ddmin): Replays subsets of the failing trace against a reset database and keeps the smallest one that still fails the same invariant, typically 2 operations in the bundled examples.
4. Reporter (Multi-Format Audit Dispatcher): Formats findings into OASIS SARIF 2.1.0, JUnit XML, Markdown Step Summaries, OpenTelemetry OTLP JSON, interactive HTML reports, and Mermaid sequence diagrams.

System Requirements & Installation

ChaosSQL requires only Go 1.22 or higher (if building from source) or can be downloaded directly as a standalone precompiled binary.

Method 1: Quick Install via Go Toolchain

go install github.com/bregaldahq/chaossql/cmd/chaossql@latest

Method 2: Static Compilation from Git Repository

# 1. Clone the official repository
git clone https://github.com/bregaldahq/chaossql.git
cd chaossql

# 2. Compile high-performance static binary
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/chaossql ./cmd/chaossql

# 3. Verify installation
./bin/chaossql --help

Method 3: Execution via Docker Container

docker run --rm -v $(pwd):/workspace -w /workspace ghcr.io/bregaldahq/chaossql:latest run specs/banking.yaml

Your First Test in 5 Minutes (Step-by-Step)

Let us create and test a classic banking lost update scenario (anomaly P4), where two concurrent clients withdraw funds simultaneously from the same account under permissive transaction isolation.

Step 1: Create Scaffolding with chaossql init

The init subcommand scaffolds a complete scenario directory with ready-to-run template files:

chaossql init quickstart_banking --driver sqlite

The generated directory structure contains:

• schema.sql: Table schemas and DDL index definitions.
• seed.sql: Initial DML dataset seeding.
• chaos.yaml: Declarative specification for database engine, workers, invariants, and operations.
• README.md: Scenario contextual documentation.

Step 2: Define the DDL Schema (schema.sql)

-- Bank accounts table
CREATE TABLE accounts (
    id INT PRIMARY KEY,
    owner TEXT NOT NULL,
    balance INT NOT NULL
);

Step 3: Seed Initial Data (seed.sql)

-- Initial balance of $1,000 for Alice
INSERT INTO accounts (id, owner, balance) VALUES (1, 'Alice', 1000);

Step 4: Configure the Specification (chaos.yaml)

version: "1.0"
name: "quickstart_banking"
description: "Verify balance integrity under concurrent withdrawals"

database:
  driver: "sqlite"
  schema: "schema.sql"
  seed: "seed.sql"

engine:
  workers: 4          # 4 concurrent goroutines
  iterations: 20      # 20 withdrawal operations in total
  seed: 42            # Deterministic reproducible PRNG seed
  jitter_ms: [1, 5]   # Stochastic micro-delays between 1ms and 5ms

invariants:
  - name: "total_balance_consistency"
    query: "SELECT balance FROM accounts WHERE id = 1;"
    assert: "balance == 1000 - (total_completed * 100)"

operations:
  - name: "withdraw_100"
    steps:
      - "SELECT balance FROM accounts WHERE id = 1 -> cur"
      - "UPDATE accounts SET balance = {cur - 100} WHERE id = 1"

Step 5: Run the Fuzzer with chaossql run

# Run by iteration count
chaossql run quickstart_banking/chaos.yaml --seed=42 --workers=4

Step 6: Analyzing Terminal Diagnostics

ChaosSQL executes all 4 workers concurrently, interleaving read (SELECT) and write (UPDATE) operations with calibrated stochastic jitter. The fuzzer catches the invariant breakdown:

• Detected Violation: balance == 1000 - (total_completed * 100) failed (expected: 0, actual: 500).
• Adya Classification: Anomaly P4_LOST_UPDATE (G-single cycle).
• Conflict Graph: T1 ──(rw)──► T2 ──(ww)──► T1.
• Delta-Debugging (ddmin): Shrunk original 20-operation execution trace to just 2 critical operations (90.0% reduction).

Flagship Built-in Demonstrations

ChaosSQL bundles 10 production-grade reference scenarios ready for instant execution via the chaossql demo subcommand: