How to document a database schema

Most database documentation goes stale the day after it is written, because it lives apart from the schema it describes: a wiki page, a slide, a diagram exported to PNG. The way to keep documentation useful is to keep it next to the schema and generate as much of it as possible, so it cannot drift. Here is a practical approach that does that.

Start from the schema itself, not a blank page

If the database already exists, do not redraw it. Import the DDL and let a tool generate the diagram and a readable version of the schema for you. DB Planner converts Postgres, MySQL, and MSSQL dumps into DBML and lays out an entity relationship diagram automatically, so your starting point is the real structure, not an approximation of it. From there, documentation is a matter of adding the context the schema cannot express on its own.

Write the "why" as notes on the tables and columns

The schema says what the columns are; documentation is mostly why. Put that where it belongs, on the object it describes. In DBML you can attach a note to a table or a single column, and it renders as markdown right on the table card: table notes in a collapsible footer, column notes in a popup opened from an icon beside the field. That keeps the explanation attached to the thing it explains, and it travels with the schema in version control instead of in a separate document.

• Explain any column whose meaning is not obvious from its name and type.
• Note the units, the allowed range, or the enum values a status column expects.
• Record the reason a table exists when it is not self-evident, not just its shape.

Let the diagram be the overview

A generated entity relationship diagram is the best high-level documentation a schema has, because it is derived from the schema and updates when the schema does. Typed fields, primary and foreign key badges, enums as their own cards, and relationship lines drawn between the exact fields involved give a reader the map in one glance. For a large schema, split it across multiple files by domain, one file per area; DB Planner resolves every file in a project together, so cross-file references still connect and the whole thing renders as one diagram.

Capture decisions and open questions in place

Some documentation is not about a specific column: it is a decision in progress, a warning, or a reminder. Draggable sticky notes on the board hold that kind of context without pretending to be part of the schema, so "denormalize before launch" or "verify the foreign key on delete" sits right next to the tables it refers to rather than in a task tracker nobody opens.

Make it shareable, and keep it that way

Documentation only helps if people can reach it. Keep the schema on a shared board your team can open rather than a file that has to be re-exported and re-sent every time it changes, so the version everyone sees is the current one. When another system needs the schema, export it as SQL, C# models, or DBML rather than transcribing it. The through-line is the same at every step: generate what you can, attach the rest to the schema, and let one always-current source do the work that a stale document cannot.

See the features overview for notes, exports, and multi-file schemas, or browse the schema templates for real examples to start from.