How to Generate Database Documentation (HTML5, PDF, Markdown)
For the person who has to hand a database schema to someone who will not open a SQL client: a client, a new joiner, an auditor.
On this page
Someone has asked for the schema, and they are not going to read your DDL. In DbSchema the answer is one dialog: open Diagram → Export HTML5 or PDF Documentation and pick the format. HTML5 gives an interactive page that opens in any browser, PDF a printable report, Markdown one section per table for a wiki or a repository. All three are generated from the design model, so nothing is typed twice and nothing is executed against the database.
The dialog asks three things: the format, the diagrams and the content. The diagrams can be the current one, all the open ones, the ones you select, or every diagram carrying the documentation tag, whose value decides the order they come out in. The content is which parts of the schema go in, with tables, columns, foreign keys, indexes and comments each switched on or off.
Draw the diagrams first, then export
The documentation follows the diagrams, so an export of one canvas holding four hundred tables produces a document nobody reads. Split the schema first: one diagram for orders, one for billing, one for the reporting views, each with its own layout. The export then carries them in order, and a reader lands on the subsystem they were asked about instead of on the whole database.
That split is also what makes the HTML5 output navigable, because each diagram becomes a vector image with the tables around it clickable.
To see what the generated output looks like before you build your own, open the sample below.
What you write in the Description field is what the reader gets
A generated document is only as useful as the comments behind it. Whatever you type in the Description field of a table or a column appears as content in all three formats, and in the HTML5 output it becomes a mouse-over tooltip as well, so a reader hovering over order_status reads what the values mean without leaving the diagram.
Beside free text, DbSchema stores comment tags on a table or a column: key and value pairs for the things a description sentence handles badly, such as the owner of a table, a sensitivity level, or a deprecation status. Tags are exported with the rest and can be read from Automation Scripts, which is how a compliance list gets built out of the model rather than out of a spreadsheet.
HTML5 interactive documentation
The HTML5 export is a set of files that opens in a browser with no server behind it and no DbSchema installed on the reader's machine. It carries the diagram as a vector image, a searchable list of tables, and the full column detail underneath. Click a table and the page jumps to its definition; hover a column and its description appears.
Put it on an intranet, attach it to a ticket, or send the folder to a client: the reader needs a browser and nothing else. For a schema that several people ask about repeatedly, this is the export that saves the most repeat explaining.
PDF and Markdown, for reviews and for repositories
PDF is the format for the review that has to be archived: a printable report with the diagram images, the table details and every column description, in one file with a date on it. When the schema holds Russian, Chinese or Japanese text, switch on Embed Unicode Font in the PDF options, or those characters do not render.
Markdown suits the opposite case. Each table becomes a section with its columns, types and descriptions laid out as a text table, which is what a GitHub repository or an internal wiki renders natively. Export it into the docs folder next to the code and the schema is one commit away from the application that uses it.
Regenerating the documentation when the schema changes
Documentation goes stale between the moment the schema changes and the moment somebody remembers to export it again, and the shorter that gap is, the less anyone has to think about it. DbSchema stores the whole design, tables and diagrams alike, in one .dbs file in XML, so the model commits to the same repository as the code and gets the same branches and reviews.
A branch per environment then means a documentation set per environment, each one generated from the model file on that branch rather than from whatever the database looked like when someone last exported it.
The export itself also runs as a Groovy script, which is what closes the gap for good: the script loads a .dbs model file and writes the HTML5 output to a path you choose.
DbSchema runs that script with no interface at all, so the whole export fits in one command in a pipeline step:
DbSchema.exe -x path/to/script.groovy
Documentation export sits in the Pro edition. Download DbSchema at https://dbschema.com/download.html, where the 15-day Pro trial comes in the same installer, split your schema into a few diagrams, fill in the Description field on the tables people ask about most, and export the HTML5 set first.
