dbx/CLAUDE.md

CLAUDE.md — dbx

Commands

go build ./...                          # compile
go test ./...                           # all tests
go test -race ./...                     # tests with race detector
go test -v -run TestName ./...          # single test
go vet ./...                            # static analysis

Architecture

• Module: git.codelab.vc/pkg/dbx, Go 1.24, depends on pgx/v5
• Single package dbx (+ dbxtest for test helpers)

Core patterns

• Cluster is the entry point — connects master + replicas, routes writes to master, reads to replicas with master fallback
• Routing is method-based: Exec/Query/QueryRow/Begin/BeginTx/CopyFrom/SendBatch → master; ReadQuery/ReadQueryRow → replicas
• Retry with exponential backoff + jitter, node fallback; retrier.do() iterates nodes then backs off
• Balancer interface (Next([]*Node) *Node) — built-in RoundRobinBalancer skips unhealthy nodes
• Health checker — background goroutine pings all nodes on an interval, flips Node.healthy atomic bool
• RunTx — panic-safe transaction wrapper: recovers panics, rolls back, re-panics
• Querier injection — InjectQuerier/ExtractQuerier pass Querier via context for service layers
• SlogLogger — adapts *slog.Logger to the dbx.Logger interface (slog.go)
• Collect/CollectOne — generic scan helpers using pgx.RowToStructByName (scan.go)
• Slow query logging — Config.SlowQueryThreshold triggers Warn-level logging in queryEnd
• PoolStats — Cluster.Stats() aggregates pool statistics across all nodes (stats.go)
• Tracer passthrough — NodeConfig.Tracer / WithTracer sets pgx.QueryTracer for OpenTelemetry
• RunInTx — test helper that runs a callback in an always-rolled-back transaction (dbxtest/tx.go)

Error classification

• IsRetryable(err) — connection errors (class 08), serialization failures (40001), deadlocks (40P01), too_many_connections (53300)
• IsConnectionError(err) — PG class 08 + string matching for pgx-wrapped errors
• IsConstraintViolation(err) — PG class 23
• PgErrorCode(err) — extract raw code from *pgconn.PgError

Conventions

• Struct-based Config with defaults() method (not functional options for NewCluster constructor, but Option type exists for ApplyOptions in tests)
• Functional options (Option func(*Config)) used via ApplyOptions (e.g., in dbxtest)
• stdlib-only tests — no testify, no gomock
• atomic.Bool for thread safety (Node.healthy, Cluster.closed)
• dbxtest.NewTestCluster skips tests when DB unreachable, auto-closes via t.Cleanup
• dbxtest.TestLogger writes to testing.T for test log output
• dbxtest.RunInTx runs a callback in a transaction that is always rolled back

See also

• AGENTS.md — universal AI agent guide with common tasks, gotchas, and ASCII diagrams