db-audit

zuvo:db-audit

Audit database interactions from code patterns through schema design to live query plans. Produces a scored report with specific, actionable fixes ranked by impact and effort.

When to use: Before releases, after adding models or queries, when latency increases, after scaling incidents, periodic health check. When NOT to use: Code quality (zuvo:review), full-stack performance (zuvo:performance-audit), security-only (/security-audit).

Mandatory File Loading

Read every file below before starting. Print the checklist.

CORE FILES LOADED:
  1. ../../shared/includes/codesift-setup.md      -- [READ | MISSING -> STOP]
  2. ../../shared/includes/env-compat.md           -- [READ | MISSING -> STOP]
  3. ../../shared/includes/run-logger.md           -- [READ | MISSING -> STOP]

Deferred (lazy load):

DEFERRED FILES (read only when needed):
  - ../../shared/includes/retrospective.md  -- read right before Phase 6 (saves ~3K tokens during audit)

Note: cq-patterns.md is NOT loaded — this is a read-only audit, not a code quality review. Loading it wastes ~7K tokens per turn.

If any CORE file is MISSING, STOP. Do not proceed from memory.

---

MANDATORY TOOL CALLS — Audit Validity Gate

This audit is INVALID if any of the tools below are skipped when their trigger condition holds. "DEFERRED", "N/A", "no diff vs prior audit" are NOT valid reasons. The presence of trigger artifacts (migrations directory, .sql files, ORM schema, etc.) is what dictates the call — not whether they changed since the last audit.

Required tool list

Tool	Trigger	Reason	Skip allowed?
sql_audit	Project has any .sql file (migrations, schema, dumps) anywhere under TARGET_ROOT	DB6/DB12/DB13 — bundles 5 gates (drift, orphan, lint, dml, complexity) that no manual scan reproduces	NO — audit FAILS if skipped while trigger holds
analyze_schema	Same as sql_audit (.sql files exist)	DB3 schema design — extracts tables/columns/FKs/relationships, generates ERD for executive summary	NO when .sql exists
diff_migrations	migrations/ dir exists (any ORM/framework)	DB6/DB13 deployment safety — classifies every op as additive/modifying/destructive with risk ranking; surfaces destructive ops missed by sql_audit lint gate	NO when migrations exist
trace_query	At least one HIGH/MEDIUM finding mentions a table OR sql_audit orphan gate flags any orphan	DB3/DB13 verification — confirms zero references for "orphan" claim and traces every cited table across DDL/DML/FK/ORM (Prisma + Drizzle)	NO when condition holds
search_columns	Always	DB12 PII discovery — find every email/password/ssn/token column across all tables	NO — always required
migration_lint	Postgres detected (any of: pg, psycopg2, @prisma/adapter-pg, postgres-js in deps) AND migrations/ dir exists	DB13 migration deployment safety (squawk: 30+ PG-specific patterns including NOT NULL without default, CREATE INDEX without CONCURRENTLY, etc.)	NO when both conditions hold
analyze_prisma_schema	prisma/schema.prisma exists	DB2/DB3/DB6 Prisma-specific schema gates (FK index coverage %, unindexed FKs, soft-delete detection, status: String smell)	NO when schema exists
explain_query	Prisma project AND any HIGH/MEDIUM finding cites a prisma.<model>.<call> query	DB1/DB2 Prisma-specific N+1 + missing-index detection via simulated EXPLAIN ANALYZE; finds risks sql_audit dml cannot see	NO when condition holds
python_audit	Language detected as Python	DB1 N+1 detection (n-plus-one-django pattern), DB9 ORM anti-patterns	NO when Python project
nest_audit	Framework detected as NestJS (@nestjs/* in deps)	DB1/DB4 NestJS DI + repository scoping issues	NO when NestJS project
analyze_django_settings + get_model_graph	django in pyproject/requirements	DB6 Django migration safety, DB3 model graph	NO when Django
scan_secrets	Always	DB12 hardcoded credentials in code or .env	NO — always required
search_patterns(pattern="unbounded-findmany") + search_patterns(pattern="await-in-loop") + search_patterns(pattern="toctou")	Always	DB1/DB5 — these are the ONLY tool-verified gates for those patterns	NO — always required