DOCUMENTATION
DBML Diagrams for Confluence
A Confluence Cloud app that draws the DBML code block on your page as an entity-relationship diagram. Back to the product page.
Getting started
Open a Confluence page and add a code block containing your DBML. For example:
Table users {
id integer [pk, increment]
email varchar(255) [unique, not null]
created_at timestamp
}
Table orders {
id integer [pk]
user_id integer [ref: > users.id]
total decimal(10,2)
}On a new line, type / and insert the DBML diagram macro — you can also use the toolbar's + button and search for “DBML”. The macro's settings open: leave Auto detect selected and choose Save. Publish the page, and the diagram appears where you put the macro.
Diagrams also render while you are still editing, so you can check one before publishing, and they work on blog posts as well as pages.
Choosing which code block a macro draws
By default the macro matches code blocks in order: the first DBML macro on a page draws the first DBML code block, the second draws the second, and so on. Blocks that are not DBML are skipped.
To choose a block yourself, select the macro, choose Edit, and pick one from the Code block list. Each entry names the block, the tables it defines and how long it is — for example Block 1 · users, orders · 12 lines — and blocks that are not DBML are marked Not DBML so you can still select one deliberately.
A block counts as DBML when it starts with Table, Ref, Enum, TableGroup or TablePartial, or when its code block language is set to dbml.
Reading a diagram
Each table is a card: its name in the header, then one row per column with the column's type. Column markers are PK for a primary key, UQ for unique, NN for not null and ++ for auto-increment. A relationship defined with ref: is drawn as a line between the two columns, a TableGroup is drawn as a labelled frame around its tables, and a table's headercolor tints its header. TablePartial definitions are resolved into the tables that use them. Diagrams follow your Confluence theme in both light and dark mode.
The full-screen viewer
Click a diagram — or tab to it and press Enter or Space — to open it full screen. Zoom in with the toolbar, the + key or the mouse wheel, and out the same way with -. Press 0 to fit the whole diagram to the screen and 1 to return to 100%. Drag the diagram or use the arrow keys to pan, and press Escape to close.
What the app draws, and what it does not
Drawn: tables and their columns, column types, primary keys, unique and not-null columns, auto-increment, relationships, table groups, schema-qualified table names, header colours and table partials.
Not drawn in this version: note text, enums as their own nodes, records, diagram views and project metadata. A schema using them still renders — those parts are simply not drawn. Long non-ASCII table and column names are measured with the painted font so they stay inside their cells.
Messages, and what to do about them
Looking for a DBML code block on this page…
The macro was just added and Confluence has not saved the block yet. It retries for about 30 seconds. If it resolves to “No DBML code block found”, pick a block in the macro's settings.
No DBML code block found
No block on the page matched this macro. Add a code block starting with Table, Ref, Enum, TableGroup or TablePartial, or select the macro, choose Edit, and pick a block.
Code block N doesn't exist
The macro points at a block that is no longer there. Select the macro, choose Edit, and pick another one.
The selected code block is empty.
The chosen block has no content. Put DBML in it, or point the macro at a different block.
The DBML has a syntax error
The parser could not read the schema. The message names the problem and shows the line; fix the DBML in the code block.
An active licence is required
The app is installed but the subscription is not active. Ask a Confluence administrator to renew it in Atlassian Administration, under Apps.
The diagram couldn't be drawn
Rendering failed. Choose Try again. If it keeps happening, choose Show details, then Copy details, and send them to support. Those details include the diagram source, which is why the app says so before you share them.
The settings couldn't be saved
The macro's settings could not be written, usually a connection problem. Choose Try again.
The page's code blocks couldn't be loaded
The page content could not be read. Reload the page, then choose Try again.
Permissions and data
The app asks for one Confluence permission, read:page:confluence, which lets it read the page or blog post a diagram macro sits on so it can find the code block to draw. It never writes to your content and never reads other pages.
Nothing is stored on our systems — we run no servers for this app. Diagrams are drawn in your own browser. Which code block a macro draws is saved by Confluence inside your page, and your browser remembers each diagram's last height, as a single number, so pages do not jump while diagrams load. Nothing is sent to us or to any third party. See privacy and security for the detail.
Licence and trial
Every Marketplace app starts with a 30-day free trial, which becomes a paid subscription unless it is cancelled. Subscriptions are managed by a site administrator in Atlassian Administration, under Apps. While a licence is inactive, macros show “An active licence is required” instead of a diagram; the macro's settings stay usable, and nothing on your pages is changed or lost.
Questions people ask
Does my schema leave Confluence?
No. The diagram is drawn in the reader's browser by code that ships with the app. There is no external rendering service.
Do readers need their own licence?
No. The app is licensed per site, and everyone who can see the page sees the diagram.
Can I export a diagram as an image?
Not in this version. You can fit the diagram in the full-screen viewer and take a screenshot.
Does it work on blog posts?
Yes, the same way as on pages.
How large a schema can it handle?
A 120-table schema renders and stays readable in the full-screen viewer.
Is this dbdiagram.io?
No. The app supports DBML, the language used by dbdiagram.io, and is not affiliated with or endorsed by Holistics.
Getting help
Email support@hourblue.com.au, Monday to Friday, and include the app's error details if you have them. For security issues, write to security@hourblue.com.au instead. Our hours and response times are on the support page.