dbdiagram for LiaScript: Design and Visualize Database Schemas with DBML

Database schema diagrams are hard to maintain. Draw them by hand and they drift from the code. Use a screenshot and it’s outdated the moment the schema changes.

The dbdiagram template solves this by rendering ER diagrams directly from text using DBML (Database Markup Language). Write your schema in a code block, add one macro, and get an interactive, zoomable diagram rendered via dbdiagram.io. Change the text, the diagram updates.

Quick Start

<!--
import: https://raw.githubusercontent.com/LiaTemplates/dbdiagram/0.0.1/README.md
-->

Three macros are available — choose based on how much interactivity you want:

DBML Syntax

DBML is a simple, readable syntax for describing database schemas.

Tables and Columns

```sql @dbdiagram
Table users {
  id       int  [pk, increment]
  name     varchar(100) [not null]
  email    varchar(100) [not null, unique]
  role     varchar(20)  [default: 'user']
  created  timestamp
}
```

Column settings: pk, not null, null, unique, increment, default: value, note: 'text'.

Relationships

Define how tables connect using ref: inline or in a separate Ref: block:

```sql @dbdiagram
Table orders {
  id          int [pk, increment]
  user_id     int [ref: > users.id]   // many-to-one
  total       decimal(10,2)
  placed_at   timestamp
}

Table order_items {
  id         int  [pk, increment]
  order_id   int  [ref: > orders.id]  // many-to-one
  product_id int  [ref: > products.id]
  quantity   int
  price      decimal(10,2)
}
```

Indexes

```sql @dbdiagram
Table posts {
  id         int [pk, increment]
  author_id  int
  title      varchar(200)
  slug       varchar(200) [unique]
  published  boolean [default: false]

  indexes {
    (author_id, published) [name: 'idx_author_status']
    slug                   [unique]
  }
}
```

Macro 1: @dbdiagram — Instant Render

Place @dbdiagram in the fence opener to render the diagram immediately, with no button. Ideal for presenting a schema as a visual illustration.

Macro 2: @dbdiagram.edit — Editable Diagram

Use @dbdiagram.edit in the fence opener to render the diagram immediately AND let learners modify it. Double-click the diagram border to open the code editor and apply changes.

``` sql @dbdiagram.edit
Table articles {
  id         int          [pk, increment]
  title      varchar(200) [not null]
  content    text
  author_id  int          [ref: > authors.id]
  published  boolean      [default: false]
}

Table authors {
  id    int          [pk, increment]
  name  varchar(100) [not null]
  bio   text
}
```

This is particularly useful in exercises: show a schema, let students extend or correct it, and see the changes reflected immediately in the diagram.

Macro 3: @dbdiagram.eval — Run Button

@dbdiagram.eval is placed after the closing fence (like @PGlite.eval). The diagram is not rendered until the student clicks the Run button. Useful when you want deliberate student interaction or want to control reveal timing.

```sql
Table blog_posts {
  id         int          [pk, increment]
  title      varchar(200) [not null]
  slug       varchar(200) [unique]
  content    text
  author_id  int          [ref: > users.id]
  created_at timestamp
}
```
@dbdiagram.eval

PGlite Integration

The PGlite template includes a built-in ERDIAGRAM; command that generates a dbdiagram.io diagram automatically from the live database schema. This creates a seamless workflow: define tables with DDL, run ERDIAGRAM;, and see the visual schema without switching tools.

```sql
CREATE TABLE authors (
  id   SERIAL PRIMARY KEY,
  name VARCHAR(100)
);

CREATE TABLE books (
  id        SERIAL PRIMARY KEY,
  title     VARCHAR(200),
  author_id INT REFERENCES authors(id)
);

ERDIAGRAM;
```
@PGlite.eval(library)

Full Template Demo

Use Cases

Database design courses — Present normalized schemas as interactive diagrams. Students see foreign keys, cardinalities, and index definitions at a glance. The editable variant lets them redesign tables as part of an exercise.

ER diagram exercises — Give students an incomplete schema in @dbdiagram.edit and ask them to add a missing table or relationship. No drawing tool needed.

Schema review and documentation — Embed a living schema diagram in a LiaScript course that serves both as lecture material and as documentation. Update the DBML text, the diagram updates.

Teaching data modeling principles — Compare 1NF, 2NF, 3NF by showing before/after schemas side by side using two @dbdiagram blocks.

Cross-template learning — Use dbdiagram in combination with PGlite: design the schema visually, implement it with DDL, verify it, and re-render the diagram from the live database with ERDIAGRAM;.

Technical Facts

Try It

Related Templates

• PGlite — full PostgreSQL with built-in ERDIAGRAM; that renders via dbdiagram
• Mermaid — text-based diagrams: ER, flowcharts, sequence, and more
• SQLite — relational SQL in the browser
• DuckDB — analytical SQL for data-heavy schemas