Database Documentation

Database documentation turns a live schema into something readable. DBX collects tables, columns, indexes, and relationships into a snapshot, merges it with notes you write yourself, and renders a browsable reference. The same snapshot serializes to DBML, so the diagram tools and CI checks read exactly what the viewer shows.

Notes live in a plain JSON file that you can commit next to your migrations, which makes schema documentation reviewable in pull requests.

Open Documentation

Right-click a table in Object Browser and choose Documentation. The viewer opens on the current connection, database, and schema.

The sidebar switches between Schemas and Table Groups. Search covers tables, columns, and groups at once. Each table page lists columns, indexes, References, and Referenced by, so relationships read in both directions.

Notes and Groups

Notes accept Markdown and render inline in the index. Every edit autosaves; the header shows Saving…, then Saved. A failed write is reported rather than swallowed, and your text is kept so the next edit retries.

Groups store a hue, not a fixed colour. Lightness and chroma come from the active theme, so a group stays legible in both light and dark mode — and the same hue becomes a [color: #rrggbb] value when exported to DBML.

Local Notes and Database Comments

A column that has a database COMMENT ON value and a note written in DBX shows your note marked LOCAL, with the database comment preserved underneath. Nothing is overwritten in the database — DBX never issues DDL for documentation, and the original comment is always recoverable.

Where Notes Are Stored

By default each connection gets its own notes file inside the DBX data directory, so the feature works with no setup.

Set Notes file in the connection's Advanced settings (stored as docs_notes_path) to point it at a file in your repository instead. The notes file itself looks like this:

{
  "formatVersion": 1,
  "project": { "name": "Billing", "note": "# Billing\n\nOne schema per tenant." },
  "groups": [{ "id": "core", "name": "Core", "hue": 210 }],
  "tables": {
    "public.orders": {
      "group": "core",
      "note": "One row per checkout.",
      "columns": { "status": { "note": "Lifecycle state." } }
    }
  }
}

Keys are schema.table and schema.table.column, folded to match how the engine treats identifier case. Writes are atomic — the file is written beside its target and renamed — so an interrupted save cannot leave a half-written file where your prose used to be.

Warnings

Documentation degrades visibly rather than silently. The viewer shows a banner when:

DBML Export

dbx dbml <connection> [--out path] [--notes path] [--schema name] [--database name] [--tables a,b]

Without --out the DBML goes to stdout, so it pipes. Notes and groups are merged only when --notes names a file; the flag is explicit, so a typo in the path fails instead of silently producing note-free output.

Output includes Table, Ref with inferred cardinality, Enum, and TableGroup blocks, and pastes directly into dbdiagram.io.

Commit the result and let CI fail on unreviewed schema drift:

- run: dbx dbml prod --notes docs/dbx-docs.json --out docs/schema.dbml
- run: git diff --exit-code docs/schema.dbml

Support and Boundaries

• Relational engines only. Document databases and key-value stores have no DBML vocabulary and are not covered.
• Tables, columns, indexes, relationships, and enums are documented. Triggers, procedures, functions, sequences, and grants are not.
• DBML export is one-way. A .dbml file is an output, never a source of truth — DBX does not import it.
• Engines without foreign key metadata produce documentation with no relationship edges, reported as a warning rather than an empty page.
• Schema history and per-table "last updated" are not tracked. Snapshots are version-stamped so this can be added later.