Заметки и оформление

Конструкции для диаграмм и документации. У них нет SQL-эквивалента: они помогают описывать и наглядно показывать схему.

Заметки

Заметки описывают элементы DBML. Есть две формы записи:

Table users {
  id int [pk]
  name varchar
  Note: 'Заметка к таблице'
  // или
  Note {
    'Заметка к таблице'
  }
}

Значение заметки — строка; для длинных текстов используйте многострочные строки.

Заметка проекта

Описывает всю схему или базу данных:

Project DBML {
  Note: '''
    # DBML - Database Markup Language
    DBML — простой и читаемый язык для описания структуры баз данных.
  '''
}

Заметка таблицы

Table users {
  id int [pk]
  name varchar
  Note: 'Хранит данные пользователей'
}

Заметка столбца

Показывается при наведении на столбец в диаграмме:

Table orders {
  status varchar [
    note: '''
      💸 1 = в обработке,
      ✔️ 2 = отправлен,
      ❌ 3 = отменён,
      😔 4 = возвращён
    '''
  ]
}

Заметка индекса

Table orders {
  created_at timestamp

  indexes {
    created_at [name: 'created_at_index', note: 'Дата']
  }
}

Пользовательские свойства

Пользовательские свойства — произвольные пары «ключ — значение» для метаданных: классификация данных, SLA, владелец и т. п. Поддерживаются у таблиц, столбцов, групп таблиц и заметок на холсте. Значение — строка (owner: "data-team") или цвет (brand_color: #3498DB).

Свойства в настройках элемента

Table users [owner: "data-team", sla_hours: "24", pii: "true"] {
  id int [pk, masking: "partial"]
  email varchar [classification: "confidential"]
}

TableGroup e_commerce [team: "growth"] {
  merchants
  countries
}

Note reminder [author: "docs"] {
  'Не забыть проверить схему'
}

Ключ без значения или повторяющийся ключ — ошибка.

Блок Metadata

Свойства можно объявить отдельно блоком Metadata, указав вид и имя элемента:

Table users {
  id int [pk]
  name varchar
}

Metadata Table users {
  owner: 'scott'
  note: 'scott — владелец'
}

Metadata Column users.id {
  pii: 'true'
  masking: 'partial'
}

Приоритет свойств

Если ключ задан в нескольких местах, приоритет растёт в таком порядке:

1. настройки в самом элементе;
2. блоки Metadata в импортированных файлах (более поздний импорт важнее);
3. блоки Metadata в текущем файле (более поздний блок важнее).

Заметки на холсте

Заметки на холсте (sticky notes) — напоминания и пояснения прямо на диаграмме:

Note single_line_note {
  'Однострочная заметка'
}

Note multiple_lines_note {
  '''
  Многострочная заметка.
  Текст может занимать несколько строк.
  '''
}

Группы таблиц (TableGroup)

TableGroup объединяет связанные таблицы:

TableGroup tablegroup_name {
  table1
  table2
  table3
}

// пример
TableGroup e_commerce1 {
  merchants
  countries
}

Заметку к группе можно задать настройкой или внутри блока:

TableGroup e_commerce [note: 'Таблицы электронной коммерции'] {
  merchants
  countries
  // или
  Note: 'Таблицы электронной коммерции'
}

Настройки группы:

• note: 'строка' — заметка;
• color: <цвет> — цвет фона группы.

Представления диаграммы (DiagramView)

DiagramView описывает несколько представлений диаграммы, каждое со своим набором элементов: Tables, Notes, TableGroups, Schemas. { * } — все элементы категории.

// все элементы
DiagramView full_view {
  Tables { * }
  Notes { * }
  TableGroups { * }
  Schemas { * }
}

// пустое представление
DiagramView empty_view {}

// выбранные таблицы
DiagramView sales_view {
  Tables {
    users
    orders
    products
  }
}

Цвета

Цвет задаётся шестнадцатеричным кодом: #rgb или #rrggbb.

Цвет заголовка таблицы:

Table users [headercolor: #3498DB] {
  id integer [primary key]
  username varchar(255) [not null, unique]
}

Цвет линии связи:

Ref: products.merchant_id > merchants.id [color: #79AD51]

Цвет группы таблиц:

TableGroup e_commerce [color: #3498DB] {
  merchants
  countries
}

Цвет заметки на холсте (none — без фона):

Note reminder [color: #F4D03F] {
  'Напоминание'
}

Note no_color [color: none] {
  'Заметка без фона'
}

Неактивные связи

Настройка inactive помечает связь как неактивную — на диаграмме она рисуется пунктиром:

Ref: posts.user_id > users.id [inactive]

Ref: posts.user_id > users.id [delete: cascade, inactive]