Supported Database Engines & Drivers

Driver Architecture and the DatabaseDriver Interface

ChaosSQL interacts with relational database engines through a high-performance abstract interface defined in internal/drivers/driver.go:

type DatabaseDriver interface {
    DriverName() string
    Open(ctx context.Context) error
    Close() error
    Reset(ctx context.Context, schemaSQL, seedSQL string) error
    BeginTx(ctx context.Context) (Tx, error)
    QueryRow(ctx context.Context, query string, args ...any) *sql.Row
    Query(ctx context.Context, query string, args ...any) (*sql.Rows, error)
    Exec(ctx context.Context, query string, args ...any) (sql.Result, error)
}

The Reset() method is pivotal for deterministic fuzzing: prior to each test iteration and before every step of the Delta-Debugging (ddmin) algorithm, ChaosSQL re-initializes the database state from scratch, guaranteeing pristine isolation between execution runs.

Pure-Go SQLite Driver (modernc.org/sqlite)

Compiling Without CGO (CGO_ENABLED=0)

Unlike legacy Go drivers based on mattn/go-sqlite3 that require external C compilers, libc headers, and shared dynamic libraries, ChaosSQL utilizes modernc.org/sqlite. This enables compiling universal static binaries with zero external build dependencies.

WAL Configuration and High-Concurrency Tuning

During driver initialization in Open(), the SQLite driver automatically enforces optimized concurrency PRAGMAs:

-- Enable Write-Ahead Logging to permit concurrent readers alongside an active writer
PRAGMA journal_mode = WAL;

-- Set lock acquisition busy timeout before failing (5,000 milliseconds)
PRAGMA busy_timeout = 5000;

Supported Connection Strings (DSN)

• :memory: or file:chaos_mem?mode=memory&cache=shared: In-memory volatile database, the fastest option for CI test suites.
• file:database.db: Persistent disk-backed database for local stress testing and crash recovery audits.

PostgreSQL Driver (pgx/v5)

ChaosSQL's PostgreSQL driver is built upon github.com/jackc/pgx/v5/stdlib, the gold standard for high-performance PostgreSQL drivers in Go.

Connection String (DSN)

postgres://chaos_user:secret_pass@localhost:5432/chaostest?sslmode=disable

Clean State Reset via Drop Cascade

To ensure a pristine database state prior to every execution, the PostgreSQL driver executes:

DROP SCHEMA IF EXISTS public CASCADE;
CREATE SCHEMA public;

Isolation Semantics: READ COMMITTED vs REPEATABLE READ vs SERIALIZABLE

• READ COMMITTED (PostgreSQL Default): Each individual statement sees a new snapshot taken at the start of that specific statement (statement-level snapshot). Highly vulnerable to Lost Update (P4) and Read Skew (A5A) when applications perform read-modify-write patterns.
• REPEATABLE READ: Implements Snapshot Isolation (SI). The entire transaction observes a consistent snapshot captured at the start of the first statement. Prevents P4 and A5A, but remains vulnerable to Write Skew (A5B) because transactions with disjoint write sets bypass write-conflict locks.
• SERIALIZABLE: Activates Ports & Grittner's Serializable Snapshot Isolation (SSI) algorithm (VLDB 2012). The engine monitors virtual read locks (SIREAD) and automatically aborts transactions participating in anti-dependency cycles with SQLSTATE 40001 (serialization_failure).

Deadlock Handling in PostgreSQL

The driver catches SQLSTATE 40P01 (deadlock_detected) and normalizes it into the canonical error type ErrDeadlockDetected, categorized by ChaosSQL under anomaly G-DL.

MySQL & MariaDB Driver (go-sql-driver/mysql)

The MySQL driver leverages github.com/go-sql-driver/mysql configured with multiple statement support (multiStatements=true).

Connection String (DSN)

root:password@tcp(127.0.0.1:3306)/chaostest?parseTime=true&multiStatements=true

InnoDB Storage Engine Particulars

• Default REPEATABLE READ: Unlike PostgreSQL, InnoDB defaults to REPEATABLE READ.
• Next-Key Locks and Gap Locks: InnoDB locks not only matched index records but also the open index intervals (gaps) between them, preventing phantom insertions (A3).
• Pessimistic Locking Deadlocks: Concurrent transactions running SELECT ... FOR UPDATE on secondary indexes are prone to gap deadlocks. ChaosSQL intercepts MySQL error 1213 (ER_LOCK_DEADLOCK) and maps it to the anomaly catalog.

Cross-Engine Differential Fuzzing with chaossql diff

The diff subcommand executes identical workloads with identical PRNG seeds across two distinct database engines simultaneously, highlighting semantic discrepancies in transactional behavior:

chaossql diff specs/banking_lost_update.yaml \
  --driver-a=sqlite --dsn-a=":memory:" \
  --driver-b=postgres --dsn-b="postgres://user:pass@localhost:5432/chaostest" \
  --seed=42