Skip to main content

Usage

There are two ways to put a diagram on a page: a ```dbml code fence for schemas written in the page, and the <DbmlDiagram> component for .dbml files, multi-file projects and anything computed.

Code fences​

Every fenced block with the language dbml becomes a diagram. Options go in the fence's meta string:

```dbml title="Billing" height=420 source
Table invoices {
id integer [pk]
customer_id integer [ref: > customers.id]
total decimal(10,2)
}

Table customers {
id integer [pk]
name varchar
}
```
Billing
Billingpublic.customers.id < public.invoices.customer_idinvoicesinvoicesid integer · primary keyidintegercustomer_id integer · foreign keycustomer_idintegertotal decimal(10,2)totaldecimal(10,2)customerscustomersid integer · primary keyidintegername varcharnamevarchar
MetaExampleMeaning
titletitle="Billing"Caption in the diagram's top-left corner; also the export file name.
heightheight=500, height=60vhHeight of this diagram. Overrides themeConfig.dbml.height.
viewview="billing"Start in a DiagramView declared in the DBML.
layoutlayout="/layouts/x.layout.json"Saved table positions, from a file in static/ (see below).
sourcesourceAdds Diagram / Source tabs so readers can see the DBML.
detaildetail=keysall columns, keys only, or table names only.
staticstaticShow the fence as highlighted DBML code instead of a diagram.
ssrssr=falseNo build-time picture for this fence (see below).
idid="billing"The diagram's anchor: #billing links to it (anchors).

Values can be double-quoted, single-quoted or bare; a bare key is true.

To show DBML code without a diagram, add static:

```dbml static
Table users {
id integer [pk]
}
```
Table users {
id integer [pk]
email varchar [unique, note: 'login']
}

The DbmlDiagram component​

In MDX, import the component and pass the DBML as value:

import DbmlDiagram from '@theme/DbmlDiagram';

<DbmlDiagram value={`Table users { id integer [pk] }`} height={240} />
PropTypeMeaning
valuestring or { files, entry }DBML source, or a multi-file project.
srcstringURL of a .dbml file served by the site (/schemas/shop.dbml); used when value is absent.
layoutlayout object or stringA parsed layout file, or the URL of one served by the site.
viewstringDiagramView to start in.
heightnumber or stringPixels or a CSS length.
titlestringCaption and export file name.
sourcebooleanDiagram / Source tabs.
detailLevel'all' | 'keys' | 'names'Overrides the site default and the layout file.
toolbararray of toolbar itemsOverrides themeConfig.dbml.toolbar.
editorUrlstringOverrides themeConfig.dbml.editorUrl.
palette'site' | 'relvista'Overrides themeConfig.dbml.palette (colours).
ssrbooleanOverrides themeConfig.dbml.ssr (build-time pictures).
idstringThe diagram's anchor on the page (anchors).
classNamestringClass on the diagram's wrapper, e.g. to override --rv-* variables for one diagram.

.dbml files​

The plugin teaches webpack to import .dbml files as text, so a schema can live next to your docs (or anywhere in the repository) and stay a normal file that dbdiagram.io and other tools can open:

import DbmlDiagram from '@theme/DbmlDiagram';
import schema from './schema.dbml';

<DbmlDiagram value={schema} title="schema.dbml" />

Or put the file in static/ and load it by URL at runtime; the site's baseUrl is added for you:

<DbmlDiagram src="/dbml/01-minimal.dbml" height={320} />
01-minimal.dbml (loaded from static/)
01-minimal.dbml (loaded from static/)public.users.id < public.posts.user_idusersusersid integer · primary key · incrementidintegeremail varchar(255) · unique · not nullemailUNNvarchar(255)created_at timestamp · default: now()created_attimestamppostspostsid integer · primary key · incrementidintegeruser_id integer · foreign key · not nulluser_idNNintegertitle varchar(200) · not nulltitleNNvarchar(200)body textbodytext

Multi-file projects​

DBML projects can split a schema over several files with use and reuse. Import each file and pass them as { files, entry }; keys are paths relative to each other, exactly as the use statements spell them:

import DbmlDiagram from '@theme/DbmlDiagram';
import main from './db/main.dbml';
import billing from './db/billing.dbml';
import users from './db/common/users.dbml';

<DbmlDiagram
value={{
entry: 'main.dbml',
files: { 'main.dbml': main, 'billing.dbml': billing, 'common/users.dbml': users },
}}
/>

The modules example in the gallery is built this way.

Layout files​

Auto-layout places every table. To keep your own arrangement, store it in a layout file next to the schema, put it in static/, and point the diagram at it. Tables listed in the file keep their positions; any others are placed around them.

```dbml layout="/layouts/01-minimal.dbml.layout.json"
Table users { ... }
Table posts { ... }
```
Saved layout: posts left, users right
Saved layout: posts left, users rightpublic.users.id < public.posts.user_idusersusersid integer · primary key · incrementidintegeremail varchar(255) · unique · not nullemailUNNvarchar(255)created_at timestamp · default: now()created_attimestamppostspostsid integer · primary key · incrementidintegeruser_id integer · foreign key · not nulluser_idNNintegertitle varchar(200) · not nulltitleNNvarchar(200)body textbodytext

With the component, layout also accepts the parsed object, so a JSON import works too:

import layout from './schema.dbml.layout.json';

<DbmlDiagram value={schema} layout={layout} />

An invalid layout file shows an error explaining what is wrong instead of a diagram.

Views​

A DiagramView in the DBML names a subset of tables. The toolbar's view menu switches between them, and view picks the starting one:

```dbml view="sales_view"
...
```

See Diagram views for the syntax and per-view layouts, and the diagram views example.

Toolbar: fullscreen, export and print​

Every diagram has a toolbar in its top-right corner. Its buttons, in order, are the items of themeConfig.dbml.toolbar (or the toolbar prop) — all of them by default:

ItemButton
viewView menu, shown when the DBML declares DiagramViews.
searchSearch tables, columns, enums, groups, notes and views, and the relationship path between two tables.
detailDetail level: all columns, keys only, or table names.
zoomZoom in / out — or use the scroll wheel, pinch and drag on the canvas.
fitFit to view.
fullscreenFullscreen — the diagram fills the screen; Esc leaves.
exportExport: SVG (vector, with embedded styles), PNG (2× resolution) or PDF… (tiled or per view).
printPrint just the diagram, scaled to fit a landscape page.
linkCopy link to this diagram, with what it shows (anchors).
open-in-editorOpen in editor — shown when editorUrl is set (the hosted editor by default).
docusaurus.config.js
themeConfig: {
dbml: {
// A reading-only toolbar: no export, print or editor link.
toolbar: ['view', 'search', 'detail', 'zoom', 'fit', 'fullscreen', 'link'],
},
},

Exports use the current colour mode, the colours and fonts the diagram shows and its detail level, and include tables you dragged where you left them. Prints use the same detail level and light colours. See Export and print for the PDF options, and Exploring diagrams for search, paths, detail levels and focus.

Open in editor carries the DBML, the layout file (when the diagram has one) and the view and table you are looking at; the positions computed at build time stay out of it, so the editor lays out a diagram without a layout file itself.

Anchors​

Every diagram's box has an id, its anchor: the id prop or fence meta, else diagram- and the title as a heading slug (title="Billing" → #diagram-billing, so a ## Billing heading keeps #billing), else diagram- and a hash of its DBML and view. #billing scrolls to the diagram like a heading link, and keys after it open the diagram at a table, view, search or path: #billing&table=invoices&view=finance. The toolbar's link button copies such a link. See deep links.

Schema diffs​

<DbmlDiff old={v1} new={v2} /> and the ```dbml-diff fence draw what changed between two versions of a schema. See Schema diff.

Build-time pictures​

docusaurus build lays out every diagram in Node and writes it into the page as a static SVG. It shows at once, without JavaScript, in print and to search engines; the interactive viewer then takes over with the same table positions, so the picture does not jump and the browser never runs the auto-layout for it.

  • src and layout paths are read from your static/ directories at build time. Remote URLs are not fetched during the build: those diagrams are drawn in the browser.
  • A diagram with errors shows its error box and the build prints a [relvista] <page>: … warning; the build itself does not fail.
  • Turn it off with themeConfig.dbml.ssr: false, the ssr={false} prop, or ssr=false on a fence.
  • Colour overrides written on .rv-viewer in custom.css do not reach the static picture; add .relvista-static-box to the selector to colour both.

Colours​

Diagrams follow the site's light/dark switch, and by default take your site's colours and fonts (primary colour for table headers and highlights, surfaces, text, fonts). Every colour is a --rv-* CSS variable you can override in custom.css, and themeConfig.dbml.palette: 'relvista' keeps relvista's own palette. See Colours and fonts for the full list.

Tables with a headercolor setting in the DBML keep their colour in both modes.