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
}
```
- Diagram
- Source
Table invoices {
id integer [pk]
customer_id integer [ref: > customers.id]
total decimal(10,2)
}
Table customers {
id integer [pk]
name varchar
}
| Meta | Example | Meaning |
|---|---|---|
title | title="Billing" | Caption in the diagram's top-left corner; also the export file name. |
height | height=500, height=60vh | Height of this diagram. Overrides themeConfig.dbml.height. |
view | view="billing" | Start in a DiagramView declared in the DBML. |
layout | layout="/layouts/x.layout.json" | Saved table positions, from a file in static/ (see below). |
source | source | Adds Diagram / Source tabs so readers can see the DBML. |
detail | detail=keys | all columns, keys only, or table names only. |
static | static | Show the fence as highlighted DBML code instead of a diagram. |
ssr | ssr=false | No build-time picture for this fence (see below). |
id | id="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} />
| Prop | Type | Meaning |
|---|---|---|
value | string or { files, entry } | DBML source, or a multi-file project. |
src | string | URL of a .dbml file served by the site (/schemas/shop.dbml); used when value is absent. |
layout | layout object or string | A parsed layout file, or the URL of one served by the site. |
view | string | DiagramView to start in. |
height | number or string | Pixels or a CSS length. |
title | string | Caption and export file name. |
source | boolean | Diagram / Source tabs. |
detailLevel | 'all' | 'keys' | 'names' | Overrides the site default and the layout file. |
toolbar | array of toolbar items | Overrides themeConfig.dbml.toolbar. |
editorUrl | string | Overrides themeConfig.dbml.editorUrl. |
palette | 'site' | 'relvista' | Overrides themeConfig.dbml.palette (colours). |
ssr | boolean | Overrides themeConfig.dbml.ssr (build-time pictures). |
id | string | The diagram's anchor on the page (anchors). |
className | string | Class 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} />
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 { ... }
```
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:
| Item | Button |
|---|---|
view | View menu, shown when the DBML declares DiagramViews. |
search | Search tables, columns, enums, groups, notes and views, and the relationship path between two tables. |
detail | Detail level: all columns, keys only, or table names. |
zoom | Zoom in / out — or use the scroll wheel, pinch and drag on the canvas. |
fit | Fit to view. |
fullscreen | Fullscreen — the diagram fills the screen; Esc leaves. |
export | Export: SVG (vector, with embedded styles), PNG (2× resolution) or PDF… (tiled or per view). |
print | Print just the diagram, scaled to fit a landscape page. |
link | Copy link to this diagram, with what it shows (anchors). |
open-in-editor | Open in editor — shown when editorUrl is set (the hosted editor by default). |
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.
srcandlayoutpaths are read from yourstatic/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, thessr={false}prop, orssr=falseon a fence. - Colour overrides written on
.rv-viewerincustom.cssdo not reach the static picture; add.relvista-static-boxto 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.