# DBML Studio for Obsidian

Draws a `.dbml` model as an ER diagram inside a note — the same diagram frame
the documentation sites embed, fed by the plugin instead of by a web server.

Desktop only: the plugin reads the model from disk with Node's `fs`, and the
models it is written for live outside the vault.

## Install

In Obsidian: **Settings → Community plugins → Browse**, search for
"DBML Studio", install it and turn it on. Obsidian keeps it up to date from
there.

By hand, for a version not in the directory yet: download `main.js`,
`manifest.json` and `styles.css` from its release in this repository (`0.2.4`
and later) into `<vault>/.obsidian/plugins/dbml-studio/`, creating the folder,
and turn the plugin on in **Settings → Community plugins**. The plugin unpacks
its diagram frame from `main.js` on the first start. Versions `0.2.0` to
`0.2.3` were released from DBML Studio's repository, before the plugin moved
here: they are among
[its releases](https://github.com/AKonyshev/dbml-studio/releases).

## What it does outside the note

The Community plugins directory asks a plugin to say these, and they are worth
knowing anyway.

- **Files outside the vault.** A block's `model:` is a path, resolved from the
  vault's root or from the note's folder, and `..` may take it out of the
  vault — that is what it is for. The models a documentation vault draws
  usually live beside the documentation they describe (an Antora or MkDocs
  site's `models/`), not inside the vault, and copying them in would leave two
  versions to drift apart. The plugin reads only the files blocks name, only
  when a note with the block is drawn or **Refresh diagrams** runs, and never
  writes them.
- **No network.** The plugin downloads nothing and sends nothing anywhere:
  the model is read from disk and handed to the diagram frame inside
  Obsidian's own window. The frame is the documentation sites' one, which on
  a site can fetch a model by URL; hosted by the plugin, it is given the
  model in a message instead and requests nothing.
- **Its own frame, unpacked into its own folder.** The diagram is drawn by a
  page — `frame/embed.html`, about 16.4 MB — that ships inside `main.js`,
  gzipped. On the first start, and after every update, the plugin compares
  `frame/BUILD` in its plugin folder with the build it carries and, when it is
  missing or different, writes `frame/embed.html` and then `frame/BUILD`
  there. The page has to be a file in the plugin folder because an `<iframe>`
  needs a URL of its own to load it from (see "How it works"). This is not
  self-updating: nothing is fetched, and the file written is the one the
  installed version came with. A start with an up-to-date `frame/` writes
  nothing. When the write fails, each block says so.

## A block

````markdown
```dbml
model: /../models/library.dbml
tables: library.author_group, library.author
height: 600
```
````

- **`model`** — required. With a leading `/` the path starts at the vault's
  root, otherwise at the note's own folder; `..` is allowed and usually
  needed. When the file cannot be read, the note names the path as it was
  resolved and why: missing, no permission, or a folder where a file
  belongs.
- **`tables`** — optional. Names separated by commas, or a list, `[a, b]`.
  Full (`schema.table`) and short names both work while the short one is
  unambiguous. Without it the whole model is drawn.
- **`height`** — pixels, a whole number above zero. 500 by default.
- **`theme`** — `light` or `dark`. Without it the diagram follows Obsidian's
  theme and switches with it.

Lines starting with `#` are comments. A key the block does not know is an
error shown in the note, not something skipped.

The keys are the MkDocs plugin's (DBML Studio's `packages/mkdocs-dbml`), and so
is the rule
for which blocks are diagrams: a block is one only when it has a line
starting with `model:` and opens — past blank lines and comments — with one
of the four keys. Anything else, DBML itself included, stays code.

What is not the same: the MkDocs plugin reads the block as YAML, and this one
reads lines. Quoted values (`model: "a.dbml"`), YAML block lists (`- a` on
lines of their own instead of `[a, b]`), and a comment trailing a value on
the same line are YAML's and are not understood here — each is read as part
of the plain text after the `:`, not stripped. A block written in the form
above means the same in both.

In Live Preview the block the cursor is in shows as its source, not as a
diagram — that is how Obsidian lets any code block be edited, Mermaid
included, and a plugin cannot change it. Right after a note opens the cursor
sits at its first line, so a note that starts with a diagram shows that one
as text until the cursor leaves it. Reading view always draws every block.
When the cursor leaves a block, Obsidian renders it afresh, and its frame
loads again — about a second.

## Commands

- **Refresh diagrams** (**Обновить диаграммы** in Russian) — re-reads every
  model on screen and sends it to its diagram again. Tables keep their
  places; new ones are laid out. The plugin does not watch the files. Each
  file is read once, and one that cannot be read is one notice, however many
  blocks draw it.

## Build from source

Needs Node 20.19 or later. From the repository root:

```bash
npm ci
npm run build
npm run install:vault -- /path/to/vault
```

Then turn the plugin on in Settings → Community plugins, and reload Obsidian
after every later install.

`npm run build` vendors the frame into `frame/` and then bundles `main.js`
with the frame inside it; `npm run build:plugin` alone refuses, naming the
file, when `frame/` is not there. `install:vault` refuses when `main.js` is not
built, copies `main.js`, `manifest.json` and `styles.css` — what the Community
plugins directory installs — and removes the vault's `frame/`, so the plugin
unpacks the one it carries on the next start.

The plugin's manifest is the repository root's `manifest.json`: the Community
plugins directory reads it from there, and `versions.json` beside it maps each
version to the Obsidian it needs.

A zip for installing by hand — a `dbml-studio/` folder inside, to unzip into
`<vault>/.obsidian/plugins/`, written to `dist/`. Built locally only; releases
do not carry it:

```bash
npm run package
```

Releasing is `npm run release:github -- <version>`, which checks the release
and pushes its tag; GitHub Actions then builds, attests and releases it. See
`RELEASING.md`.

### The frame

The diagram frame is not built here. It comes from the npm package
[`dbml-frame`](https://www.npmjs.com/package/dbml-frame), which
[DBML Studio](https://github.com/AKonyshev/dbml-studio) builds and publishes
with every release, and this repository pins it to an exact version in
`package.json`. `npm run build` unpacks the package's frame and its manifest
into the one document the plugin carries (see "How it works").

To build against a frame that is not published yet — a branch of DBML Studio —
build the package there, then point this build at it:

```bash
# in the DBML Studio checkout
yarn build:web && yarn workspace dbml-frame build

# here
DBML_FRAME_SOURCE=../dbml-studio/packages/dbml-frame npm run build
```

`node scripts/vendor-frame.mjs --source <dbml-frame package dir>` does the same
for the vendoring step alone. A build made that way carries that frame's
`BUILD`, and is not a release: a release is built from the pinned package,
and `npm run release:github` refuses while `DBML_FRAME_SOURCE` is set.

## How it works

The plugin is a host, not a second visualizer. `frame/embed.html` is DBML
Studio's frame (the `dbml-frame` package) as one self-contained document:
`scripts/vendor-frame.mjs` walks the package's `frame/manifest.json` by the
rule in DBML Studio's `packages/web/README.md` ("Packaging the frame from the
manifest"), bundles the frame's chunks into one inline module script with
esbuild, and puts the stylesheet inline too. The result is about 16.4 MB of
HTML and names no other file. `frame/BUILD` is the package's `BUILD`, which
names the DBML Studio commit the frame was built from.

`scripts/build-plugin.mjs` then puts both into `main.js` with esbuild's
`define` — the document gzipped and base64-encoded (nearly all of `main.js`,
which is 3.9 MB), `BUILD` as it is — and refuses to build when `frame/` is not
there. It gzips with `fflate` rather than Node's own zlib, whose output
depends on the zlib a Node was built with: the directory rebuilds `main.js` and
compares it with the released one, so it has to come out the same bytes on
every Node and OS. The directory installs `main.js`, `manifest.json` and
`styles.css` and nothing else, so the frame travels the only way it can. On load,
`src/frameArchive.ts` compares the plugin folder's `frame/BUILD` with the
carried one and, when it is missing or different, unpacks the document with
the browser's own `DecompressionStream` and writes it through the vault
adapter (the plugin folder is not a vault file, so `Vault` does not address
it), `BUILD` last: a write cut short leaves no `BUILD` claiming a whole frame.
Blocks wait for this before they create a frame element.

One file because it has to be. Obsidian serves the plugin folder through
`getResourcePath`, and a document loaded that way runs inline scripts but has
every external script it names refused (`net::ERR_BLOCKED_BY_CLIENT`, found
in the live app 2026-09-25). A `blob:` URL would run with the window's own
origin and `srcdoc` with none, so neither is used. If Obsidian ever starts
allowing an external script from a `getResourcePath` document, `frame/` could
go back to the multi-file shape DBML Studio's `packages/mkdocs-dbml` vendors —
but until
then the build refuses, naming the chunk, a frame it cannot inline: a dynamic
import, an emitted asset, `url(` in the CSS, or `</script` / `<!--` in the
JavaScript.

The plugin reads the model and hands its text to the frame with a `document`
message of the `dbml-frame` protocol; a theme change travels as `theme`, and
the frame asks to be expanded with `expand`. The vocabulary is DBML Studio's
`packages/web/src/embed/frameHost.ts`, compiled into `dbml-frame/protocol` and
imported by `src/hostProtocol.ts`, so a change to a message there breaks this
repository's type check when `dbml-frame` is bumped. The frame is
told apart from every other window by identity — the window the plugin
created — rather than by origin, because the Obsidian window and the frame
never share one.

Each block draws in its own window: a note opened in a popout keeps its own
document, and the block's frame, its message listener and its expand lock
all live there rather than in Obsidian's main window. At most one diagram is
expanded per window at a time — a second expand in the same window puts the
first back; Escape does too.

An expanded diagram covers the note's pane, not the whole window. Its box is
`position: fixed`, and Obsidian's workspace leaf contains `fixed` (found in
the live app, Obsidian 1.13.7), so the pane is what it fills; the frame's
toolbar stays visible, and puts it back. That is accepted: the spec asks for
a diagram expanded over the workspace, and the note's pane is where the
reader was working.

A note's tab dragged into another window takes its blocks along without
rendering them again, and each frame reloads there. The plugin follows through
the element's `onWindowMigrated` hook. Each diagram:

- is released from the old window's expand lock, so that window is unlocked
  and an expanded diagram arrives collapsed
- moves its listener and poster to the new window
- reloads in the application's theme, and greets the reloaded frame with its
  model in that theme

The plugin's code, though, runs in the main window, and a browser stamps a
message's `event.source` with the window of the code that calls
`postMessage` — so a popout's frame, posted to directly, would hear the main
window and drop everything, since it accepts only its parent. Each
`FrameView` therefore posts through a one-line function compiled by its own
window's `Function` constructor, which speaks as that window whoever calls it.

A frame loads only when its block first comes on screen. Obsidian renders
every block twice while a note is open — reading view, and the Live Preview
editor it keeps hidden — and each frame is the 16.4 MB document above, some
70 MB once running. The frame element is placed at its full height at once,
but gets its `src` from an `IntersectionObserver` of the block's own window,
so the hidden copy never loads. The model sent before then waits for the
frame's hello. The theme in the frame's URL, which it paints in before the
hello, is read when `src` is written, not when the block rendered: a diagram
scrolled to after a theme switch loads in the new theme.

Measured in Obsidian 1.13.7 with four diagrams in a note: the frames load in
0.5–1.4 s and the diagrams are visible about 1.8 s after the note opens.
Obsidian's main window never stalls (worst 1 ms), because the frames run out
of process; each loaded frame costs about 70 MB.

All the text a reader of a note sees — block errors, the read failure, the
command name — is English, or Russian when Obsidian's own language is
Russian. The plugin asks Obsidian with `getLanguage()` on load (Obsidian
restarts to change language). The two catalogs are `src/i18n/locales/en.ts`
and `ru.ts`, one shape (`src/i18n/catalog.ts`); `src/i18n/locales/` is the one
path where Cyrillic lives, the way it did in DBML Studio, where a test
(`packages/json-table-schema-visualizer/src/i18n/__tests__/sourceLanguage.test.ts`)
enforced it. Everywhere else in this repository's source stays English.

## Tests

```bash
npm test
```

Jest in jsdom, over the pure modules and the frame's side of the
conversation; one test spawns `scripts/vendor-frame.mjs` against a fixture
`dbml-frame` package and runs the script it inlines. `main.test.ts` runs the plugin itself
against a stand-in for the `obsidian` module, which ships types only. The
wiring into Obsidian — windows, views, scrolling, the theme — is checked by
hand, against a real vault: `docs/test-cases.md`.