DOCUMENTATION

DBML Diagrams for Jira

A Jira Cloud app that draws the DBML code blocks on an issue as entity-relationship diagrams. Back to the product page.

Getting started

Open a Jira issue and add a code block containing your DBML to its description, or to a comment. 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)
}

Save it. Then, under the issue title, open the apps button (View app actions) and choose DBML diagrams. The panel appears above the issue's Activity section and draws the diagram. It stays on that issue from then on, for everyone who opens it.

Only people who can edit an issue see DBML diagrams in that menu, so only they can add the panel. Everyone who can view the issue sees a panel once it has been added.

The first time you see the panel

The app reads the issue as you, so it never sees more than you can. The first time you see the panel, Jira may ask you to let the app access Atlassian apps on your behalf. Choose Allow access. This happens once per person, and the administrator who installed the app has already done it.

Which code blocks it draws

A code block counts as DBML when its first word is Table, Ref, Enum, TableGroup, TablePartial, Project, Note or Records, or when its language is set to dbml. Other code blocks are skipped. Each DBML block becomes its own diagram; blocks are not combined, so a Ref in one block does not connect to a table defined in another.

How diagrams are laid out

The description comes first. Every DBML block in the issue's description is drawn, in order, labelled Description block 1, Description block 2 and so on.

Then diagrams from comments. The app looks for DBML in the latest 100 comments and shows the newest three diagrams, oldest of them first. Each is labelled with who posted the comment and when, for example Comment by Alex Smith, 3 Oct 2026, with a Go to comment link that takes you to that comment on the issue. A comment holding several DBML blocks adds · block 2 and so on to the label.

Earlier diagrams on request. When there are more comment diagrams than the newest three, Show earlier comment diagrams draws the rest. On an issue with more than 100 comments, Search older comments looks through the next 100 older ones each time you choose it. This keeps the panel fast on long threads: by default it reads the issue once, however many comments it has.

When the issue changes

Edit the description or add a comment, and the panel redraws on its own within a few seconds. The diagrams already on screen stay until the new ones are ready. If a comment is edited or deleted, reload the issue to see the change.

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 Jira 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. The viewer shows the one diagram you opened.

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.

Messages, and what to do about them

No DBML code blocks on this issue

Nothing in the description or the comments is DBML. Add a code block starting with Table, Ref, Enum, TableGroup or TablePartial.

No DBML code blocks in the description or the latest 100 comments

The issue has more than 100 comments, and none of the latest 100 holds DBML. Choose Search older comments to look further back.

No DBML code blocks in those older comments.

The last search found nothing. Search again to look further back, if the button is still there.

The older comments couldn't be loaded.

The search failed, usually a connection problem. The diagrams already shown stay; choose Search older comments again.

This code block is empty.

The block is marked as DBML but has no content. Put DBML in it.

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 Jira 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 issue key and, for a diagram that failed to draw, its DBML source, which is why the app says so before you share them.

The issue's code blocks couldn't be loaded

The issue could not be read. Reload the issue, then choose Try again.

Permissions and data

The app asks for one Jira permission, read:jira-work, which lets it read the description and comments of the issue it is on so it can find the code blocks to draw. It reads as the person viewing the issue, reads only that issue, and never writes to your issues.

Nothing is stored on our systems — we run no servers for this app. Diagrams are drawn in your own browser. Jira remembers which issues the panel has been added to, as it does for any app panel, and your browser remembers each diagram's last height, as a single number, so the issue does not jump while diagrams load. Above each diagram from a comment the app shows the comment's author and date, which you can already see on the issue; it keeps neither. 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, the panel shows “An active licence is required” instead of diagrams, and nothing on your issues is changed or lost.

Questions people ask

Does my schema leave Jira?

No. The diagram is drawn in the viewer's browser by code that ships with the app. There is no external rendering service.

Do people need their own licence?

No. The app is licensed per site. Everyone who can view the issue sees the panel, after confirming Allow access once.

Can I hide a diagram, or choose which ones show?

Not in this version. Every DBML block in the description is drawn, and the newest comment diagrams show first, with the rest a click away.

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.

How large a schema can it handle?

A 120-table schema renders and stays readable in the full-screen viewer, and an issue with 16 diagrams and 120 comments loads in a few seconds.

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.