Schema diff
A schema changes over time, and a review should show how. relvista compares two versions of a
DBML schema table by table and column by column and draws the result as one diagram: added
tables, columns and refs in green, removed ones in red (struck through, still where they were),
changed ones in amber with a badge such as +1 −1 ~1. A list of every change comes with it.
Changes: 2 added, 2 removed, 2 changed
- Changed:
users.email: varchar → text - Changed:
users.email (notNull): false → true - Added:
column users.display_name - Removed:
column users.legacy_flag - Changed:
orders.total: decimal(10,2) → decimal(12,2) - Added:
column orders.status - Added:
table order_items - Removed:
table sessions - Added:
ref orders.id < order_items.order_id - Removed:
ref users.id < sessions.user_id
The DbmlDiff component
import DbmlDiff from '@theme/DbmlDiff';
import v1 from './schema-v1.dbml';
import v2 from './schema-v2.dbml';
<DbmlDiff old={v1} new={v2} title="Accounts, v1 → v2" />
| Prop | Type | Meaning |
|---|---|---|
old, new | string or { files, entry } | The two versions: DBML source, or multi-file projects. |
oldSrc, newSrc | string | URLs of .dbml files served by the site, instead of old / new. |
layout | layout object or string | Saved positions for the new version (a layout file). |
view | string | A DiagramView of the new version. |
height, title | as for DbmlDiagram | |
summary | boolean | The change list under the diagram. Default true. |
id | string | The diff's anchor on the page. |
detailLevel | 'all' | 'keys' | 'names' | Start at another detail level. |
ssr, palette, toolbar, className | as for DbmlDiagram |
Renamed tables are recognised when their columns are identical: sessions renamed to
user_sessions is one changed table, not one removed and one added. Refs, indexes, checks,
enums and their values, table groups, sticky notes, views and project settings are compared too.
The dbml-diff fence
For a quick before/after in a page, write both versions in one fence, separated by a line of exactly three dashes:
```dbml-diff title="Add a status to orders" id="orders-status"
Table orders {
id integer [pk]
total decimal(10,2)
}
---
Table orders {
id integer [pk]
total decimal(10,2)
status varchar [not null, default: 'open']
}
```
Changes: 0 added, 0 removed, 1 changed
- Added:
column orders.status
The meta string takes the DbmlDiagram fence options (title, height, view, layout,
detail, id, ssr, static) plus summary=false. Only the first --- line splits the
fence.
In the page's HTML
Like every diagram, a diff is drawn at build time: the toned picture and the change list are in
the HTML, so they show without JavaScript, in print and to search engines. In the browser the
interactive viewer takes over in place, with its legend chip (+2 −1 ~2), search and export. A
diff has no Open in editor button; open the two files in the editor and use Compare
instead.
Compare in the editor
In the editor, Compare… (Mod+Alt+D) compares the open document with another version:
- File… — pick or drop a
.dbmlfile; - Paste — paste DBML text;
- URL — any
httpsaddress that allows cross-origin requests (GitHubbloblinks are rewritten to the raw file); - Git ref — when the document came from GitHub, a branch, tag or commit of the same file.
By default the other version is before and your document after; the swap button turns that around. In compare mode the diagram shows the diff, a Changes panel lists every change (filter by added, removed or changed; click one to go to it), and the code pane becomes a side-by-side text diff. You can keep editing: the diff follows. Export works on the toned picture, and Copy summary copies the change list as Markdown, ready for a pull request. Esc or Exit compare goes back.