claude-db

Audit a database schema, ORM model, or migrations for design and performance — produces two independent 0-100 scores (Design & Integrity + Performance & Scale) plus a prioritized, evidence-backed report. Read-only; never writes or migrates. Use when the user asks to audit, analyze, review, check, or score a database, schema, data model, migrations, indexes, keys, referential integrity, types, constraints, query patterns, partitioning, or connection pooling — for Postgres, MySQL, Mongo, DynamoDB, Cassandra, pgvector, ClickHouse, Neo4j, and friends.

Render a production-readiness GO/NO-GO grid for a database — runs a read-only audit, then maps the findings onto a fixed launch checklist (PITR/backups, RLS on tenant tables, FK indexes, money-as-numeric, timestamptz/UTC, connection pooling sized, migration reversibility, secrets-not-in-schema, charset/utf8mb4). Each row is PASS/WARN/FAIL/NEEDS-LIVE with the finding id, topped by a plain-language verdict. Read-only. Use when the user asks if a database is production-ready, ready to launch/ship, a go/no-go, a pre-launch or readiness checklist, or what to fix before going live.

Unified cross-paradigm anti-pattern catalog (M19) — relational and NoSQL smells that no single structural module owns cleanly: EAV / generic key-value tables, the "god table" with hundreds of columns, comma-separated lists in a column, polymorphic associations without FK, boolean-flag soup, Mongo unbounded array growth, deeply nested documents, the document fan-out / "join in app code" trap, Redis as a relied-on durable primary store. Each finding is re-homed to inherit the natural module's category. Feeds the Design & Integrity AND Performance & Scale scores depending on the smell.

Audit concurrency correctness — transaction isolation level, lost-update / read-modify-write races, queue-worker contention (SKIP LOCKED), and idempotency for key-value / document / wide-column writes. Module M14. Feeds the Performance & Scale score.

Audit connection management — serverless functions opening direct Postgres connections, transaction-mode pooler misuse (PgBouncer / Supabase / prepared statements), and pool sizing against backend max_connections. Module M15. Feeds the Performance & Scale score.

Audit data-integrity constraints — missing NOT NULL on required columns, absent CHECK constraints for domain rules, missing UNIQUE on natural keys, and the over-nullable UNIQUE trap where NULLs silently permit duplicates. Module M5. Feeds the Design & Integrity score (Constraints category).

Audit column defaults and generated columns — application-side timestamps that should be DB defaults, non-deterministic or wrong defaults, derived values that should be GENERATED ALWAYS / computed columns instead of drift-prone duplicated data, and identity/sequence defaults. Module M6. Feeds the Design & Integrity score (Tipos category, shared with M4).

Engine selection (M0) — at design/start time, recommends a database paradigm and engine for a described workload (access patterns, consistency needs, scale, team, platform), and names the runner-up with the trade-off you're accepting. M0 is a RECOMMENDATION, not a scored audit module — it emits no findings and never contributes to the Design or Performance score. Walks the decision tree in references/engine-selection-tree.md and is honest about lock-in and operability instead of fabricating benchmarks.

Audit index bloat — exact-duplicate indexes, redundant indexes whose key is a prefix of another, and unused indexes that only cost write amplification and storage. Module M12. Feeds the Performance & Scale score.

Audit index coverage for the query workload — composite index column order (ESR), covering and partial indexes, specialized types (GIN/GiST/BRIN, FTS, geo, JSONB-GIN), and foreign keys with no covering index. Module M11. Feeds the Performance & Scale score.

Audit primary-key strategy — missing PK (severity 5), surrogate vs natural keys, UUIDv4 index fragmentation vs time-ordered UUIDv7/ULID/bigint, and int4/serial exhaustion on high-volume tables. Module M2. Feeds both the Design & Integrity (Llaves) and Performance & Scale (Escala) scores.

Migration-safety lint (M22) — the static contract the migration-safety auditor (MSA) and db-migration-writer enforce on a candidate migration BEFORE it runs. Checks reversibility (down migration present / expand-contract), lock level (does it take ACCESS EXCLUSIVE on a hot table), table rewrite (full-table rewrites on type/default changes), destructive ops (DROP COLUMN/TABLE, TRUNCATE), unsafe enum mutation, NOT NULL without default on a large table, and schema drift between the declarative artifact and migration history. Feeds the Performance & Scale score.

Audit multi-tenant data isolation — tenant model fit (shared rows vs schema vs database), missing or unenforced tenant scoping, the tenant_id-leading composite index/key requirement, and cross-tenant leak risk where queries or constraints omit the tenant boundary. Module M9. Feeds both the Design & Integrity (Seguridad) and Performance & Scale (Escala) scores.

Audit naming conventions — inconsistent table/column casing and pluralization, ambiguous or reserved-word identifiers, untyped/opaque columns, inconsistent FK and boolean naming, and identifiers that fight the engine's case-folding rules. Module M7. Feeds the Design & Integrity score (Naming category, low weight).

Audit relational schema normalization — 1NF through 3NF violations, repeating groups and CSV-in-a-column, partial and transitive functional dependencies, and the inverse trap of premature or undisciplined denormalization. Module M1. Feeds the Design & Integrity score (Modelado category).

Orchestrates a full database audit — detects the stack(s), dispatches read-only auditor subagents in parallel by paradigm, merges and dedupes their findings, computes the two never-blended scores (Design & Integrity + Performance & Scale) via score.mjs, and renders the report. Invoked by the audit command; not usually called directly.

Audit horizontal scaling topology — declarative partitioning fit for large/time-series tables, hot-partition / skewed partition-key risk, and premature sharding that adds complexity before it is justified. Module M16. Feeds the Performance & Scale score.

Managed-platform fitness (M21) — checks the project against the realities of its hosting platform (Supabase, Neon, PlanetScale, Turso, Cloudflare D1, CockroachDB, Yugabyte, DynamoDB, RDS/Aurora). Engine version currency (without fabricating EOL dates), honest pricing / vendor lock-in trade-offs, and per-platform feature support — most importantly foreign-key support (PlanetScale Vitess historically restricts FKs; D1/SQLite, serverless drivers, connection limits). Feeds the Design & Integrity AND Performance & Scale scores.

Audit query-shape anti-patterns — SELECT *, structural N+1 (directional), OFFSET pagination vs keyset, and non-SARGable predicates that defeat indexes. Module M13. Feeds the Performance & Scale score.

Audit foreign-key integrity — missing FKs that allow orphan rows (financial/auth = severity 5), absent or unsafe ON DELETE/ON UPDATE actions, reference cycles, and composite-FK column/order mismatches. Module M3. Feeds both the Design & Integrity (Integridad referencial) and Performance & Scale (Query) scores.

Audit read-scaling correctness — read-your-writes consistency when reads are routed to replicas, and materialized-view staleness / refresh strategy. Module M17. Feeds the Performance & Scale score.

Audit access control and data protection — Row-Level Security state, PII handling, encryption at-rest and in-transit (TLS / sslmode), and SQL-injection exposure from raw concatenation. Module M10. Feeds the Design & Integrity score.

Specialized-engine fitness (M20) — checks whether a vector, time-series/OLAP, graph, or search store is configured correctly for its job. M20a vector (dimensions match the embedding model, distance metric matches how the model was trained, HNSW/IVFFlat params present), M20b time-series/OLAP (hypertable/partition fit, continuous aggregates, compression), M20c graph (edge modeling, supernode risk, index-backed lookups), M20d search (analyzer/mapping, FTS config). Feeds the Design & Integrity AND Performance & Scale scores per sub-module.

Audit storage operability — VACUUM / autovacuum health and table-and-index bloat, transaction-ID wraparound risk (sev-5), and tombstone accumulation on wide-column stores. Module M18. Feeds the Performance & Scale score.

Audit temporal and lifecycle modeling — soft-delete consistency and its uniqueness/query traps, presence and integrity of an audit/history trail, and retention / GDPR right-to-erasure handling (hard delete vs anonymization, retention windows). Module M8. Feeds the Design & Integrity score (Temporal category).

Audit column types and precision — money stored as float/double (severity 5), naive timestamp vs timestamptz/UTC, jsonb used to evade schema, enum-vs-lookup-table choice, and charset/collation (utf8mb4, case-insensitive collation). Module M4. Feeds the Design & Integrity score (Tipos category).

Greenfield database design — pick the right engine for a new project, compare it against the boring default, and hand back a starter data model with a diagram. Recommendation mode (module M0); never scored, never destructive. Use when the user is starting fresh and asks what database to use, how to model a new app, which engine fits, or for a schema/data-model from scratch.

Explain a database schema, model, or a single finding in plain language, with a paradigm-aware diagram — what the tables/collections/keyspaces are, how they relate, and where the data lives. Read-only; teaches, does not change anything. Use when the user asks to explain, describe, walk through, draw, or diagram a schema, a data model, a relationship, or what a specific audit finding means.

Opt-in writer (the /claude-db:fix command). Applies the safe, reversible schema/migration changes from an audit — adding indexes, NOT NULL/CHECK/UNIQUE constraints, missing FKs, type corrections, default/generated columns — as expand-contract migrations. Dry-run preview by default; writes only after explicit per-change confirmation, and only via the migration-writer subagent. Runs only when the user invokes it — never auto-triggered.

Tier-1 live read-only introspection. Connects to the running database through a DB MCP server's read-class tools (preferred) or a least-privilege read-only connection string, reads catalogs only (no table data, no writes), and upgrades affected findings to confidence established. Enforces the read-only contract; when no live access is available it marks the dependent checks needs_api — never a silent pass. Invoked by db-orchestrator and the auditors when a check needs runtime truth.

Lint a database migration for safety before it runs — classify lock level, table rewrite, and reversibility; flag destructive/blocking operations; and propose an expand-contract rollout. Read-only analysis by default; any data-loss step requires an explicit token handshake before the writer is involved. Use when the user asks to review, lint, check, or de-risk a migration, an ALTER/DROP, an enum change, a backfill, or a schema change before deploying.

Coach the user on what to fix first — rank the audit findings into a single, ordered to-do list by score impact and effort, and explain why each item is where it is. Read-only; advises, does not change anything. Use when the user asks what to do next, what to fix first, what matters most, how to prioritize, or where to start after an audit.

Recompute and display the two database scores (Design & Integrity + Performance & Scale) from a findings JSON, without re-auditing. Use to re-show or refresh the scores after an audit, to re-score with a different paradigm profile, or to score a saved findings file.

Generate FK-aware, deterministic sample/seed data from a database schema, ORM model, or migrations — INSERT statements emitted in dependency order (parents first), values derived from row index so output is stable and reviewable. Read-only; never writes to a database. For dev/test fixtures only. Use when the user asks to seed, generate sample/test/fixture/dummy/fake data, populate tables, or create starter rows for Postgres, MySQL, SQLite, and friends.

Detects the database stack(s) of a project — paradigm, engine, ORM, platform, and the authoritative source_of_truth — by wrapping scripts/detect-stack.mjs. Emits the stacks array plus routing (which paradigm profile and module set each stack drives) and the source_of_truth precedence. Never guesses an engine; an empty result routes to /claude-db:start. Invoked by db-orchestrator (Phase 1); not usually called directly.

Guided, jargon-free starting point for people with no schema and no database yet — a short 7-question wizard that turns "I want to build an app" into a concrete engine recommendation and a first data model. Zero artifacts required. Use when the user has nothing to audit, asks how to begin, says they're not technical, or doesn't know what database or schema they need.