Guia de Início Rápido & Primeiros Passos

O Que é o ChaosSQL?

O ChaosSQL é um Fuzzer Determinístico de Concorrência e Invariantes para Bancos de Dados SQL, criado por Ricardo Bregalda (Studio Bregalda). Em sistemas concorrentes e microsserviços modernos, bugs de concorrência como Lost Updates, Write Skew, Dirty Reads e Deadlocks são extremamente difíceis de reproduzir e depurar. Testes de unidade convencionais são sequenciais e determinísticos por natureza, enquanto testes de carga estocásticos (como JMeter ou k6) geram ruído desmedido e raramente reproduzem as trocas de contexto (context switches) críticas necessárias para disparar a anomalia.

O ChaosSQL aborda essa lacuna fundamental unindo a engenharia do caos com três pilares da computação teórica:

• Agendamento com Jitter Semeado: O motor intercala os workers com atrasos sorteados por um PRNG semeado, então a mesma spec com a mesma semente repete o mesmo agendamento. O proxy transparente adiciona um agendador no estilo PCT, inspirado em Burckhardt & Musuvathi (ASPLOS 2010). Nenhum dos dois prova a ausência de bugs; eles tornam reproduzíveis os agendamentos explorados.
• Classificação Automática de Anomalias via Grafos de Adya: Reconstrói o Grafo de Serialização Direta (Direct Serialization Graph) com base na tese seminal de Atul Adya (MIT 1999) e nas observações de caixa-preta do Elle (VLDB 2020), identificando arestas de conflito rw (anti-dependência), ww (sobreposição) e wr (dependência de leitura).
• Delta-Debugging (ddmin): Implementa o algoritmo de Andreas Zeller com replays memoizados e uma auditoria final de 1-minimalidade, reduzindo um trace com falha ao menor conjunto de operações que ainda produz a mesma assinatura de falha.

Requisitos de Sistema & Instalação

O ChaosSQL requer apenas o ambiente Go 1.22 ou superior (caso deseje compilar a partir do código-fonte) ou pode ser baixado diretamente como binário standalone.

Método 1: Instalação Rápida via Go Toolchain

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

Método 2: Compilação Estática a Partir do Repositório Git

# 1. Clonar o repositório oficial
git clone https://github.com/bregaldahq/chaossql.git
cd chaossql

# 2. Compilar binário estático de alta performance
CGO_ENABLED=0 go build -ldflags="-s -w" -o bin/chaossql ./cmd/chaossql

# 3. Testar a instalação
./bin/chaossql --help

Método 3: Execução via Docker Container

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

Seu Primeiro Teste em 5 Minutos (Passo a Passo)

Vamos criar e testar um cenário clássico de perda de atualização bancária (Lost Update, anomalia P4), onde dois clientes sacam dinheiro simultaneamente da mesma conta sob isolamento permissivo.

Passo 1: Criar o Scaffolding com chaossql init

O comando init cria a estrutura de diretórios e arquivos de modelo prontos para execução:

chaossql init quickstart_banking --driver sqlite

A estrutura de arquivos criada é:

• schema.sql: Esquema das tabelas e índices DDL.
• seed.sql: Carga inicial de dados DML.
• chaos.yaml: Especificação do motor, workers, invariantes e operações.
• README.md: Documentação contextual do cenário.

Passo 2: Definir o Esquema DDL (schema.sql)

-- Tabela de contas bancárias
CREATE TABLE accounts (
    id INT PRIMARY KEY,
    owner TEXT NOT NULL,
    balance INT NOT NULL
);

Passo 3: Inserir a Carga Inicial (seed.sql)

-- Saldo inicial de R$ 1.000 para Alice
INSERT INTO accounts (id, owner, balance) VALUES (1, 'Alice', 1000);

Passo 4: Configurar a Especificação (chaos.yaml)

version: "1.0"
name: "quickstart_banking"
description: "Verificação de integridade de saldo sob saques simultâneos"

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

engine:
  workers: 4          # 4 goroutines concorrentes
  iterations: 20      # 20 operações de saque no total
  seed: 42            # Semente determinística reproduzível
  jitter_ms: [1, 5]   # Micro-atrasos estocásticos de 1ms a 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"

Passo 5: Executar o Fuzzer com chaossql run

chaossql run quickstart_banking/chaos.yaml --seed=42 --workers=4

Passo 6: Analisando o Diagnóstico no Terminal

O ChaosSQL executa os 4 workers simultaneamente, intercalando as operações de leitura (SELECT) e escrita (UPDATE) com jitter estocástico. O fuzzer detecta a violação da invariante:

• Violação Identificada: balance == 1000 - (total_completed * 100) falhou (esperado: 0, real: 500).
• Classificação Adya: Anomalia P4_LOST_UPDATE (G-single cycle).
• Grafo de Conflito: T1 ──(rw)──► T2 ──(ww)──► T1.
• Delta-Debugging (ddmin): Reduziu o trace original de 20 operações para apenas 2 operações críticas (90.0% de redução).

Demonstrações Flagship Embutidas

O ChaosSQL inclui 10 cenários pré-configurados prontos para execução imediata via comando chaossql demo: