How to Generate Database Documentation (HTML5, PDF, Markdown)

Someone has asked for the schema, and they are not going to read your DDL. DbSchema reads the schema from the database into a model, its own copy of the schema. From the model, DbSchema writes the documentation: one HTML5 page that opens in any browser, a PDF, or a Markdown file. The export writes nothing to the database.

1. Choose File → New Model and connect to the database. DbSchema reads the schema and draws its tables on a diagram.
2. Open the diagram you want to document.
3. Choose File → Export As... → HTML5/PDF Documentation, or press Ctrl+D.
4. Type a Title, and choose HTML5, PDF or Markdown under Format.
5. Under File Path, type the file name in a folder that exists, then press Generate. DbSchema creates the file, but not the folder.

To document a large schema, split it by topic first with Diagram → New Diagram, such as one diagram for orders and one for billing. Each diagram becomes one section of the documentation, so a reader goes straight to the part they asked about. The first list under Content in the dialog picks which diagrams go in (Document several diagrams).

Table and column comments become the descriptions

What a reader needs is what each table holds and what each column means. DbSchema takes both from the comments on tables and columns. It reads those comments from the database along with the tables. In PostgreSQL 17, you write them with COMMENT ON:

CREATE SCHEMA shop;
CREATE TABLE shop.customers (
    customer_id integer PRIMARY KEY,
    email       varchar(120) NOT NULL UNIQUE
);
COMMENT ON TABLE shop.customers IS 'Everyone who created an account';
COMMENT ON COLUMN shop.customers.email IS 'Login and contact address, unique per customer';

DbSchema 10.5.2 read this schema and generated this Markdown:

### Table shop.customers
Everyone who created an account

|Idx |Name |Data Type |Description |
|---|---|---|---|
| * 🔑  | customer\_id| integer  |  |
| * 🔍 | email| varchar(120)  | Login and contact address, unique per customer |

Where a comment is missing, add it in DbSchema: double-click the table header on the diagram and type in the Comment box. While DbSchema is connected, it saves the comment in the database as well as in the model. For the same steps on MySQL, see How to document a MySQL database schema.

HTML5, PDF or Markdown

Send HTML5 to someone who will browse the schema. It is a single .html file that opens in any browser, with no server and no DbSchema. A search box finds tables, columns and comments, and pointing at a column on the diagram shows its comment. Below the diagram, each table has a card with its columns, indexes and foreign keys. Open a sample to see what your reader gets.

Send a PDF for a review that has to be printed or archived, as in this sample PDF. If names or comments use Cyrillic, Arabic, Chinese or other non-Latin letters, tick Embed Unicode Font. The PDF then carries a font for those letters, and grows by about 15 MB.

Choose Markdown to keep the documentation next to the code. DbSchema writes one .md file, laid out like the Markdown above, and an .svg image of each diagram. The Idx column marks keys and indexes with HTML codes such as 🔑, which GitHub shows as icons. Export into the repository's docs folder, and a schema change and its documentation go through the same pull request.

Regenerate the documentation from a script

To export the documentation again without opening DbSchema's window, run a Groovy automation script. This script loads a model file and writes one HTML5 file that documents all of its diagrams:

import com.wisecoders.dbschema.schema.Expose
import com.wisecoders.dbschema.schema.store.ProjectLoader

def loader = new ProjectLoader()
new File(parameters[1]).withInputStream { input -> loader.parse(input) }
def project = loader.project

def expose = new Expose(new File(parameters[2]), project, project.diagrams)
project.diagrams.get(0).generateHtmlDocumentation(expose)
println 'Wrote ' + parameters[2]

Run it from a scheduled task or a pipeline step, with full paths:

"C:\Program Files\DbSchema\DbSchema.exe" -x C:/scripts/export-docs.groovy C:/models/shop.dbs C:/docs/shop.html

For PDF or Markdown, call generatePdfDocumentation or generateMarkdownDocumentation instead. Have the pipeline check the output for the Wrote line. DbSchema exits with code 0 even when the script fails.

The script documents the model as it was last saved to its .dbs file. After a schema change, update the model with Database → Refresh Model from Database, and save it. Keep the model file in Git with File → Git Collaboration, so that each branch carries its own model.

The free Community Edition documents a diagram of up to 12 tables, with "DbSchema Trial" across the diagram image. DbSchema Pro documents any diagram, and saves the model file that the script reads. Download DbSchema, which includes a 15-day Architect trial, connect it to your database, and export the HTML5 page of the diagram that people ask about most. To weigh DbSchema against other tools first, read Best database documentation tools.