Skip to main content

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.

Accounts, v1 → v2
Accounts, v1 → v2public.users.id < public.orders.user_idpublic.orders.id < public.order_items.order_idpublic.users.id < public.sessions.user_idusersusers+1 −1 ~1id integer · primary keyidintegeremail text · unique · not nullemailUNNtextlegacy_flag booleanlegacy_flagbooleandisplay_name varchardisplay_namevarcharordersorders+1 ~1id integer · primary keyidintegeruser_id integer · foreign keyuser_idintegertotal decimal(12,2)totaldecimal(12,2)status varcharstatusvarcharorder_itemsorder_itemsorder_id integer · foreign keyorder_idintegersku varcharskuvarcharquantity integerquantityintegersessionssessionsid integer · primary keyidintegeruser_id integer · foreign keyuser_idintegertoken varchartokenvarchar
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" />
PropTypeMeaning
old, newstring or { files, entry }The two versions: DBML source, or multi-file projects.
oldSrc, newSrcstringURLs of .dbml files served by the site, instead of old / new.
layoutlayout object or stringSaved positions for the new version (a layout file).
viewstringA DiagramView of the new version.
height, titleas for DbmlDiagram
summarybooleanThe change list under the diagram. Default true.
idstringThe diff's anchor on the page.
detailLevel'all' | 'keys' | 'names'Start at another detail level.
ssr, palette, toolbar, classNameas 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']
}
```
Add a status to orders
Add a status to ordersordersorders+1id integer · primary keyidintegertotal decimal(10,2)totaldecimal(10,2)status varchar · not null · default: openstatusNNvarchar
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 .dbml file;
  • Paste — paste DBML text;
  • URL — any https address that allows cross-origin requests (GitHub blob links 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.