/database-documentation

name: database-documentation
version: 0.0.1
license: MIT
description: >-
  Generate grounded-and-verified, engine-agnostic database documentation that reaches 100% parity with the
  real schema. Introspects the LIVE database as ground truth and cross-validates it against ORM models,
  migrations, generated types, seeds, and application queries, then proves completeness by diffing the docs
  back against the database. Produces ER diagrams (mermaid), per-table data dictionaries, and a
  machine-readable schema.json. Works with PostgreSQL, MySQL, SQL Server, and SQLite across any ORM (Prisma,
  TypeORM, Drizzle, Sequelize, Knex, Django, Rails) or raw SQL. Use when asked to document a database,
  produce an ERD or data dictionary, write db/schema docs, audit schema drift, or refresh existing DB docs.
compatibility: >-
  Best results need read access to the live database (via a DB CLI, docker exec, or a connected DB MCP
  server) and, on platforms that support it, parallel subagents. Degrades gracefully without them.

database-documentation

Document a database so completely and accurately that the docs are **provably** the schema, not a plausible guess at it. A half-correct schema doc is worse than none: people trust it and write broken code.

The one principle: grounded AND verified

Every statement in the output must be:

• **grounded** — traceable to a concrete source, preferring the **live database** (introspection of the

system catalog). ORM models, migrations, generated types, and seeds are *claims about* the database, not the database; the catalog is what actually runs.

• **verified** — confirmed by re-introspecting the live database and diffing it against the generated docs

until the diff is empty or every remaining difference is explicitly justified. Never write "documentation is complete" — instead make the diff empty and show it.

A frontier model left to itself reads the ORM, writes confident prose, and ships an **incomplete and partly hallucinated** schema (missed check-constraint enums, wrong `ON DELETE`, omitted legacy tables, invented columns). This skill exists to defeat exactly that. Two mechanisms do it: (1) the live DB is the oracle, and (2) judgment is never one agent's call — independent adversaries hunt for what one pass misses.

Scope (v1): relational/SQL only

Targets PostgreSQL, MySQL, SQL Server, SQLite. If you detect a document store (MongoDB) or graph database, **say so and stop on that store** — do not emit relational docs for it (silent mis-documentation is the worst outcome). Note it as out of scope rather than guessing.

Workflow

Run these phases in order. Each names its exit artifact. Keep all scratch (intermediate extractions, the working CSM) in a single `.database-documentation/` scratch dir or your platform scratchpad — the **only durable deliverables are the docs and `schema.json`**.

Phase 0 — Discover (read-only)

1. **Fingerprint** the engine + version and the ORM(s): look for `schema.prisma`, `*.entity.ts` + datasource, `drizzle.config.*`, `knexfile.*` + `migrations/`, Django `models.py`, Rails `schema.rb`, raw SQL DDL. Find the engine + version from the datasource/provider, `docker-compose.yml` image tags, and connection URLs in `.env*`. 2. **Find the live-DB reachability path**, trying in this order and stopping at the first that works: a connected **DB MCP server** → **`docker compose exec` / `docker exec`** into the DB container (read creds from compose env) → a **local DB CLI** (`psql`/`mysql`/`sqlcmd`/`sqlite3`) against host:port from `.env`. **Prove it** with one trivial query (`SELECT 1`, list tables) before continuing. If the DB is down but a compose file defines it, offer to start it. **Never print credentials**: treat passwords/DSNs read from `.env`/compose as secrets — keep them only in the command you execute, and **redact them** (`password=***`) in anything you show or write to the docs. 3. **Inventory every other surface**: migrations dir (+count), generated client/`*.d.ts`, seeds/fixtures, and grep the app for raw SQL / query-builder calls. Note existing `docs/db/` — if present this is a *refresh*: load it to diff for drift and to match house style. 4. **Announce the tier** you reached (see Degradation ladder) so the reader knows the confidence level.

Exit: a short discovery note — engine, ORM, reachability tier, the exact verified live-DB command, surface paths.

Phase 1 — Extract every surface (parallel where possible)

Extract each available surface **independently** into the Canonical Schema Model shape (see `references/csm-contract.md`). On platforms with subagents, run one extractor per surface in parallel, and **do not let them see each other's output** — independent agreement is real evidence; shared context is groupthink.

**Object-class checklist — extract EVERY class; skipping one is the most common failure.** Copy this list and confirm each is present in `schema.json` with a live count:

• [ ] tables · [ ] columns (type+nullable+default+comment) · [ ] primary keys · [ ] foreign keys (+ON DELETE/UPDATE)
• [ ] unique constraints · [ ] check constraints · [ ] indexes (+partial/expression) · [ ] enums (+values)
• [ ] **sequences** · [ ] **triggers** · [ ] **views** (+definition) · [ ] routines (functions/procedures)

Sequences, triggers, and routines are routinely forgotten because they are not columns — extract them explicitly. Capture view / trigger / routine **bodies in full and verbatim** — never abbreviate, summarize, or elide with `...`; a truncated definition is an incomplete (wrong) doc. **`schema.json.enums` = DB-NATIVE enum types only.** A string column with a `CHECK (col IN (...))` goes under that table's `check_constraints` (not `enums`); an app-level-only value set goes in the column description marked "app-enforced". Putting a non-native enum in `enums` is a hallucination against the live schema.

• **Live introspection (authoritative).** Read