Notes & Table Groups

Notes and table groups help you document and organize your database schema. Notes add human-readable descriptions to tables, columns, and the canvas itself. Table groups visually cluster related tables together on the ERD diagram.

Sticky Notes

Sticky notes are standalone notes that appear as floating cards on the ERD canvas. They are not attached to any table — use them for project-wide documentation, design decisions, or instructions for collaborators.

Note my_note {
  'This is a project-wide note.
  It can span multiple lines.'
}

Multiline Notes

Note text is enclosed in single quotes and can span as many lines as needed:

Note design_decisions {
  'Database Design Notes
  =====================

  1. All tables use auto-incrementing integer PKs.
  2. Soft deletes are used for users and workspaces.
  3. Timestamps use UTC timezone throughout.
  4. Currency amounts stored as decimal(12,2) in cents.'
}

Sticky Note Appearance

On the canvas, sticky notes render as draggable cards. You can:

• Position them by dragging to any location on the canvas
• Color them to visually distinguish different types of notes

Note todo [color: #f39c12] {
  'TODO: Add audit logging tables
  for compliance requirements.'
}

Note warning [color: #e74c3c] {
  'WARNING: The payments table schema
  is pending review by the security team.'
}

TIP

Use colored sticky notes to create a visual legend on your canvas — yellow for TODOs, red for warnings, green for approved sections.

Table Notes

Add a descriptive note directly inside a table definition with Note:. The note describes the table's purpose:

Table users {
  id int [pk, increment]
  email varchar(255) [not null, unique]
  created_at timestamp [default: `now()`]

  Note: 'Core user accounts table. Each row represents a registered user with a verified email address.'
}

Table notes appear in the table header area on the canvas and are exported as COMMENT ON TABLE statements in PostgreSQL or as inline comments in other dialects.

Multiline Table Notes

Table notes can also span multiple lines:

Table orders {
  id int [pk, increment]
  status varchar(20) [not null, default: 'pending']

  Note: 'Customer purchase orders.
  Status transitions: pending → paid → shipped → delivered.
  Cancelled orders are soft-deleted (see deleted_at column).'
}

Column Notes

Attach a note to a specific column using the note: setting:

Table users {
  id int [pk, increment]
  email varchar(255) [not null, unique, note: 'Must be verified before login is allowed']
  password_hash varchar(255) [not null, note: 'bcrypt hash, never store plaintext']
  login_count int [default: 0, note: 'Incremented on each successful authentication']
  last_login_at timestamp [note: 'NULL if user has never logged in']
}

Column notes are useful for documenting:

• Business rules and constraints not captured by the schema
• Expected data formats or patterns
• Relationships to external systems
• Migration or deprecation plans

In PostgreSQL exports, column notes become COMMENT ON COLUMN statements.

Table Groups

Table groups visually cluster related tables together on the ERD canvas. They render as labeled containers that surround the grouped tables.

TableGroup ecommerce {
  orders
  order_items
  products
  categories
}

TableGroup auth {
  users
  sessions
  permissions
  roles
}

Group Display Names

Use quoted strings to give a group a human-friendly display name:

TableGroup "E-Commerce" {
  orders
  order_items
  products
}

TableGroup "User Authentication" {
  users
  sessions
  permissions
}

Group Colors

Customize the color of a table group to visually distinguish different domains:

TableGroup "Auth" [color: #e74c3c] {
  users
  sessions
  permissions
}

TableGroup "Billing" [color: #2ecc71] {
  invoices
  payments
  subscriptions
}

TableGroup "Content" [color: #3498db] {
  posts
  comments
  tags
}

The color applies to the group boundary and label on the canvas.

TIP

Combining table groups with table colors creates a highly readable diagram. Use the same color for a group and all tables within it to create clear visual domains.

Group Notes

You can add notes to table groups to describe the domain:

TableGroup "Payment Processing" [color: #2ecc71] {
  invoices
  payments
  refunds

  Note: 'All payment-related tables. Integrates with Stripe via webhooks.'
}

Group notes appear as descriptions beneath the group label on the canvas.

Practical Organization Example

Here is a complete example showing how notes and table groups work together to document a schema:

// ---- Project-wide documentation ----

Note overview [color: #3498db] {
  'SaaS Application Schema v2.3
  Last updated: 2024-03-15
  Owner: Backend Team'
}

Note conventions [color: #f39c12] {
  'Naming conventions:
  - Tables: plural snake_case
  - Columns: singular snake_case
  - Foreign keys: {referenced_table_singular}_id
  - Timestamps: created_at, updated_at, deleted_at'
}

// ---- Auth domain ----

TableGroup "Authentication" [color: #e74c3c] {
  users
  sessions
}

Table users {
  id int [pk, increment]
  email varchar(255) [not null, unique, note: 'Verified via email OTP']
  password_hash varchar(255) [note: 'NULL for OAuth-only users']
  created_at timestamp [default: `now()`]

  Note: 'Core user accounts. Supports email/password and Google OAuth login.'
}

Table sessions {
  id int [pk, increment]
  user_id int [not null, ref: > users.id]
  token_hash varchar(255) [not null, note: 'HMAC-SHA256 hash of refresh token']
  expires_at timestamp [not null]

  Note: 'Active login sessions. Revoked on logout or password change.'
}

// ---- Content domain ----

TableGroup "Content" [color: #3498db] {
  posts
  comments
}

Table posts {
  id int [pk, increment]
  user_id int [not null, ref: > users.id]
  title varchar(200) [not null]
  body text
  created_at timestamp [default: `now()`]
}

Table comments {
  id int [pk, increment]
  post_id int [not null, ref: > posts.id]
  user_id int [not null, ref: > users.id]
  body text [not null]
  created_at timestamp [default: `now()`]
}

This example demonstrates sticky notes for project documentation, table groups with colors for domain organization, table notes for entity descriptions, and column notes for field-level documentation.