Schema Documentation

The people who need to read a schema, such as a reviewer, a new developer or an auditor, often don't run DbSchema. DbSchema writes the documentation for them as one HTML5 file, a PDF or a Markdown file, with the diagram and a description of every table, column, index and foreign key.

Generating the documentation reads the model and changes neither the model nor the database. DbSchema Pro documents any diagram. In the Community Edition, DbSchema documents a diagram of up to 12 tables, and the diagram image then carries "DbSchema Trial" across it, as it does during the trial.

Generate the documentation

Generate it when someone needs to read the schema without DbSchema, or before a review.

1. Open the diagram you want to document.
2. Choose File → Export As... → HTML5/PDF Documentation, or press Ctrl+D.
3. Type a Title. It shows at the top of the documentation.
4. Choose HTML5, PDF or Markdown under Format.
5. Under File Path, type the file name, or press ... to choose it.
6. Press Generate.

With Preview in Browser ticked, DbSchema opens the HTML5 page or the PDF when it's ready. A file name without an extension gets .html, .pdf or .md, and a folder gets an index file of the chosen format inside it.

The folder must exist, because DbSchema creates the file but not the folder. On Windows, a missing folder stops Generate with:

C:\docs\shop\index.html (The system cannot find the path specified)

To refresh the documentation on a schedule, for example every night, generate it with a Groovy script. The link Automate using Java Groovy scripts in the dialog opens Automation Scripts, whose examples include a Documentation folder.

Choose what goes in

The first list under Content picks the diagrams, as Document several diagrams shows. The boxes below it decide what each diagram's part of the documentation holds:

Option	What it adds
Text Documentation	A description of each table with its columns
Table of Contents	A list of the tables, with links
Diagram Vector Image	The diagram as an SVG image, sharp at any zoom
Image Mouse-Over Tooltips	The comments, shown when you point at a table or column in the image
Legend	A box in the image with the title, a logo and your company text
All Columns	Every column; untick it for only the columns the diagram shows
Indexes, Foreign Keys	The indexes and foreign keys of each table
View Query	The query of each view
Triggers, Functions and Procedures, Sequences, User Data Type	These objects, by name
Procs/Triggers Text	The SQL source of functions, procedures and triggers

Indexes and Triggers need Text Documentation, and Image Mouse-Over Tooltips needs Diagram Vector Image. Generate refuses to run when both Diagram Vector Image and Text Documentation are unticked.

The Settings part changes how the result looks:

Setting	What it does
Dark Theme	Writes a dark HTML5 page; PDF stays light
Full-Size Diagrams	Fills the browser window, with each diagram at its drawn size
Use Separate SVG File	Writes the image to its own .svg file, without links to the text
Escape Comments	Shows <, > and & in comments as text instead of reading them as HTML

Without Full-Size Diagrams, the page content is at most 1180 pixels wide and each diagram shrinks to fit it. Drag a full-size diagram to move around in it.

Read the HTML5 documentation

The HTML5 documentation is a single .html file. Open it in any browser, with no server and no internet connection.

• The top bar shows the title, the database type, the number of tables and the date of the export. Its search box finds tables, columns and comments.
• The sidebar lists the tables when Table of Contents and Text Documentation are both ticked, and lists the diagrams when you document several. Otherwise DbSchema leaves the sidebar out, and it also hides in a browser window narrower than 900 pixels.
• The diagram card shows the diagram. Drag to pan, hold Ctrl while you turn the mouse wheel to zoom, and point at a column to read its comment. Clicking a column, or its icon, jumps to that column in the description of its table.
• Below the diagram, a card for each table lists its columns with their data types and constraints, then its indexes, its foreign keys and the foreign keys that reference it. Show in diagram jumps to the table in the diagram.

What the icons mean

The icons mark the columns on the diagram in DbSchema and in the HTML5 documentation, which repeats this legend below the diagram:

Icon	Meaning
Key	The column belongs to the primary key
Fingerprint	The column belongs to a unique key or a unique index
Magnifying glass	The column belongs to an index
Arrow up and right, on a plate	Foreign key: the column refers to another table
Arrow down and left, on a plate	Referenced by: a foreign key of another table refers to the column
Red asterisk	Mandatory: the column is NOT NULL
Speech bubble after the name	The column has a comment

On the diagram, the icon at the right end of a column without a foreign key shows the kind of data: Σ for numbers, Tт for text, a clock for date and time, and a switch for true or false.

On the diagram, a smaller key, fingerprint or magnifying glass marks a column that comes second or later in its index, such as product_id in the primary key of order_items. The HTML5 documentation draws every icon at one size; point at an icon there to read the name and the columns of its index.

Clicking the foreign key arrow of a column on the diagram lists the tables linked through that column. For orders.customer_id the list holds Show customers via orders_customer_id_fkey, which scrolls to customers because the diagram already shows it. A table that the diagram doesn't show yet is listed as Add, and choosing it adds the table, as Add the related tables shows. In the HTML5 documentation, pointing at the arrow names the table it refers to, such as "References customers ( customer_id )".

Add descriptions to tables and columns

A comment explains a table or a column in a sentence, and the documentation prints it under the table name and in the Description column.

1. Double-click the table header on the diagram.
2. Type the description in the Comment tab above the table's tabs.
3. Press OK.

A column has its own Comment box in the column dialog, as Add a column shows. DbSchema keeps the comment in the model, and when you're connected, OK writes it to the database at once. In PostgreSQL 17, the statement for the table comment is:

COMMENT ON TABLE shop.customers IS 'Everyone who created an account';

Add your company name and logo

The Legend box in the diagram image shows the title, a logo and one line of text, which reads "DbSchema.com © DATE Wise Coders" until you change it.

1. Choose Edit → Settings.
2. In the General tab, open HTML & PDF Documentation.
3. Type your text in Logo Text. Write DATE where the export date should go.
4. In Logo Link, type the address that the text links to.
5. To use your own logo, paste SVG code into Logo Icon, without the <svg> tag. An <image href="data:image/png;base64,..." .../> tag works too.
6. Press OK.
7. In the documentation dialog, tick Legend.

In the HTML5 and Markdown documentation, DbSchema replaces DATE with the export date, so "Shop Inc. DATE" becomes "Shop Inc. 2026-10-18". The PDF puts the date, such as 18-10-2026, in front of the text in the title line of each diagram page and prints DATE as typed, so leave DATE out if you generate PDFs. Show the Hover Tip Note adds the line "Read schema comments as mouse-over tooltips" to the Legend box.

Generate a PDF

Choose PDF when you need a document to print or to attach to an email. The diagram gets a page of its own, sized to the diagram, and Page Size sets the pages that describe the tables, from Letter, Legal, Tabloid and Executive to A0 through A5 and B0 through B2. Tick Landscape, to the right of Page Size, to turn those pages sideways.

If your names or comments use Cyrillic, Arabic, Chinese or other non-Latin letters, tick Embed Unicode Font. The PDF then carries the font and grows by about 15 MB. The setting PDF Comments as Tooltips, in Edit → Settings → HTML & PDF Documentation, adds the comments to the diagram page as PDF notes.

Generate Markdown

Choose Markdown to keep the documentation next to your code, for example in a Git repository or a wiki. DbSchema writes a .md file and, for each diagram, an .svg image of it named after the diagram, such as MainDiagram.svg. With one diagram, the image sits next to the .md file. With several diagrams, the images go into a folder named after the .md file.

The Markdown file holds, in this order:

1. The title and a "Generated using DbSchema" line.
2. With several diagrams, a numbered list of them under Layouts, and Prev, Index and Next links on each.
3. With Table of Contents ticked, a numbered list of the tables, with links.
4. For each diagram, its image.
5. For each table, a heading, its comment, and a table of its columns with Idx, Name, Data Type and, where comments exist, Description.
6. Under each table, its indexes, foreign keys, constraints and triggers, where it has any.
7. For each view, its query and its columns. Then functions, procedures and sequences, where you ticked them.

The Idx column marks each column with a symbol: * mandatory, 🔑 a key for the primary key, 🔍 a magnifying glass tilted left for unique, 🔎 one tilted right for an index, ⬈ an arrow up and right for a foreign key, and ⬋ an arrow down and left for referenced by. DbSchema writes the symbols as these HTML codes, which GitHub and most wikis show as the symbols. A part of the result for the shop database:

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

|Idx |Name |Data Type |Description |
|---|---|---|---|
| * 🔑  ⬋ | customer\_id| integer  DEFAULT nextval('shop.customers_customer_id_seq'::regclass) |  |
| * | first\_name| varchar(60)  |  |
| * 🔍 | email| varchar(120)  | Login and contact address, unique per customer |

##### Indexes
|Type |Name |On |
|---|---|---|
| 🔑  | customers\_pkey | ON customer\_id|
| 🔍  | customers\_email\_key | ON email|

Document several diagrams

Each diagram becomes one section of the documentation, so a large schema split into diagrams by topic, such as customers, orders and products, gives documentation with the same topics. The first list under Content in the documentation dialog picks the diagrams:

Choice	Diagrams it documents
Current Diagram	The diagram you have open
Selected Diagram	The diagrams you tick in the list next to it
Open Diagrams	Every diagram open in a tab
Diagrams with 'documentation' tag	Every diagram that carries the tag documentation, ordered by the tag's value

To tag a diagram:

1. Choose Diagram → Diagram Properties.
2. Open the Tags tab and double-click the first row.
3. Type documentation as the Key and a number such as 1 as the Value, which sets the diagram's place in the documentation.
4. Press Ok.

The tag changes only the model. If no diagram carries it, Generate stops and asks you to set the tags.

Common problems

What do the small and large magnifying glasses mean?

On the diagram, a small magnifying glass marks a column that is the second or a later column of an index, and the large one marks the first column. The same goes for keys and fingerprints. The HTML5 documentation draws them at one size, and pointing at one names its index, as What the icons mean shows.

Why does the HTML5 page have a sidebar, or none?

DbSchema writes the sidebar only when it has something to list: the diagrams, when you document several, or the tables, when Table of Contents and Text Documentation are both ticked. In a browser window narrower than 900 pixels, the page hides it.

The diagram doesn't fill the browser window

Tick Full-Size Diagrams in the documentation dialog and generate again. Without it, the page is at most 1180 pixels wide.

My company name and link don't show

The text and the link show only in the Legend box of the diagram image. Tick Legend in the documentation dialog, and set Logo Text and Logo Link in Edit → Settings → HTML & PDF Documentation, as Add your company name and logo shows.

Next steps

• Change the colors and fonts of the diagram and the documentation
• Arrange tables on diagrams
• Generate documentation from a script
• Share the model with Git