DBML Diagram для IntelliJ IDEA с офлайн превью и открытым исходным кодом

Привет! На связи Boost for Java. Развиваем DBML Diagram — open source плагин для IntelliJ IDEA и других совместимых IDE на платформе IntelliJ. Он строит ER-диаграмму рядом с открытым .dbml-файлом: меняете описание таблиц и связей — превью обновляется прямо в редакторе. Построение диаграммы работает локально, без отправки схемы во внешний сервис.

В этой статье покажем возможности версии 0.1.0, пользу работы со схемами прямо в IntelliJ IDEA и устройство плагина. Отдельно расскажем о планах интеграции с dbdiagram.io для публикации локальных изменений в общую схему. Проект открыт: будем рады предложениям, примерам проблемных схем и участию в разработке.

Плагин в JetBrains Marketplace · Исходный код на GitHub

Чем плагин полезен в IntelliJ IDEA

В нашей компании мы используем dbdiagram.io для совместного проектирования схем баз данных. Там удобно обсуждать общую модель с командой. При этом локальные изменения часто возникают во время разработки: нужно добавить поле, уточнить связь или подготовить изменение структуры под конкретную задачу.

DBML позволяет описывать такую структуру в текстовом виде: таблицы, поля, индексы и отношения. В DBML Diagram этот файл становится источником для визуального представления внутри IDE.

В IntelliJ IDEA код приложения, описание схемы и её визуальное представление находятся в одном рабочем пространстве. Открываете .dbml рядом с кодом, вносите правки и сразу оцениваете, как изменились таблицы и связи. Для построения превью не требуется подключение к работающей базе данных.

Практическая польза такого подхода:

• Меньше переключений между инструментами. Локальную правку можно сделать и проверить визуально, оставаясь в IntelliJ IDEA.

• Схема участвует в работе над задачей. Если хранить .dbml в репозитории, его изменения можно коммитить вместе с кодом и обсуждать на code review. Для истории и текстового diff доступны обычные средства Git в IDE.

• Промежуточные варианты остаются локальными. Можно подготовить изменение и посмотреть на результат до того, как делиться им с коллегами.

• Превью доступно офлайн. Для просмотра и редактирования локальной схемы не требуется доступ к dbdiagram.io.

• Результат удобно показать команде. Уже сейчас диаграмму можно выгрузить в SVG или PNG и приложить к задаче или документации.

Что уже работает в версии 0.1.0

Плагин добавляет поддержку файлов .dbml, базовую подсветку синтаксиса и три режима редактора: Code, Preview и Code + Preview. В последнем режиме описание схемы и диаграмма находятся рядом.

Изменения текста запускают обновление превью с небольшой задержкой. Если во время набора появляется ошибка разбора — например, ещё не закрыта фигурная скобка, — остаётся последняя успешно построенная диаграмма и выводится сообщение об ошибке. Поэтому во время редактирования можно продолжать ориентироваться по схеме. При этом показанная картинка до исправления ошибки относится к предыдущему корректному состоянию файла.

Для просмотра есть перемещение по диаграмме, увеличение и уменьшение масштаба, возврат к 100%, кнопка Fit и ручное обновление Refresh. Предусмотрены светлая и тёмная темы.

Диаграмму можно экспортировать в SVG или PNG. Экспортируется вся схема, включая области за пределами текущего окна просмотра. SVG удобно использовать там, где важна чёткость при масштабировании, а PNG — вставлять в статью или документацию.

Эти возможности перечислены в changelog версии 0.1.0.

DBML-код и диаграмма в одном редакторе.

Небольшой пример с пользователями и заказами

Для первого знакомства создадим файл shop.dbml с двумя таблицами:

Table users {
    id uuid [pk]
    email varchar(255) [not null, unique]
    name varchar(255)
}

Table orders {
    id uuid [pk]
    user_id uuid [not null]
    amount numeric(19,2) [not null]

    indexes {
        user_id
    }
}

Ref: orders.user_id > users.id

Здесь orders.user_id ссылается на users.id: одному пользователю может соответствовать несколько заказов. Открываем файл в режиме Code + Preview и получаем визуальное представление этой связи.

Можно добавить в orders поле created_at timestamptz и посмотреть, как изменится диаграмма. Затем — экспортировать результат через Export SVG или Export PNG. Более подробный пример из репозитория также содержит перечисление статусов заказа и составной индекс.

Какая часть DBML поддерживается

В текущей реализации есть поддержка основных конструкций для описания схемы:

• таблиц, полей, имён со схемой и псевдонимов таблиц;

• типов полей, в том числе с параметрами: varchar(255), numeric(19,2);

• распространённых настроек колонок: pk, not null, unique, increment, default и note;

• простых и составных индексов, перечислений Enum;

• отдельных объявлений Ref и ссылок внутри описания колонки;

• отношений с операторами >, <, - и <>;

• комментариев и заметок.

Парсер также формирует диагностические сообщения: например, о дублирующихся таблицах и полях или ссылках на неизвестные элементы схемы.

Это поддерживаемое подмножество DBML. Полное соответствие всем возможностям языка в версии 0.1.0 пока не заявлено; границы поддержки описаны в README.

Как устроено построение диаграммы

В проекте два основных модуля. dbml-core содержит модель схемы, парсер, алгоритм размещения таблиц и SVG-рендерер. dbml-intellij-plugin отвечает за интеграцию с IDE: редактор, подсветку, обновление превью и экспорт.

Путь от текста до картинки выглядит так:

DBML → модель схемы → размещение таблиц → SVG → превью в IDE

Такое разделение позволяет развивать разбор языка и визуализацию отдельно от редактора. Алгоритм размещения скрыт за интерфейсом DiagramLayoutEngine: в дальнейшем его можно заменить, сохранив остальную цепочку.

В планировщике обновления используется debounce на 300 мс. При новом вводе ожидающая задача отменяется и назначается следующая. Разбор текста, расчёт расположения и генерация SVG выполняются в фоновом потоке, затем результат передаётся интерфейсу IDE. Эти 300 мс — задержка перед запуском задачи, а время построения зависит от самой схемы.

Для отображения используется встроенный в IDE браузерный компонент JCEF. Он получает локально сформированные HTML и SVG. При работе превью не нужны отдельный браузер, Node.js, внешняя CLI-утилита или сетевой сервис.

Текущие ограничения

Сейчас плагин закрывает базовый сценарий редактирования DBML с просмотром диаграммы. Есть несколько ограничений, которые стоит учитывать при знакомстве с ним.

Подсветка пока лексическая. Полноценная интеграция языка с PSI ещё впереди: автодополнение, переходы к объявлениям, инспекции и рефакторинг в текущую версию не входят.

Автоматическое размещение требует развития. Используется собственный алгоритм раскладки по слоям. В плотных схемах с большим количеством связей и циклов линии могут пересекаться неудачно. Такие примеры особенно полезны для дальнейшей работы над читаемостью диаграмм.

Разбор конструкции не всегда означает полную обработку её смысла. Например, настройки связей вроде [delete: cascade] принимаются парсером, но правила каскадного удаления и обновления пока не обрабатываются дальше.

Для визуального превью нужен JCEF. Если он недоступен в окружении IDE, текстовый редактор остаётся рабочим, но диаграмма не отображается.

Эти ограничения зафиксированы в документации проекта.

Как попробовать плагин

Начать можно с карточки DBML Diagram в JetBrains Marketplace. Перед установкой посмотрите совместимость с вашей версией IDE.

Есть и путь через исходный код. Для сборки нужны Git и JDK 17; при первом запуске Gradle потребуется интернет для загрузки зависимостей.

git clone https://github.com/RomanVoronovskiy/DBML\\_Diagram.git
cd DBML_Diagram
./gradlew test buildPlugin

В Windows из PowerShell последняя команда выглядит так:

.\gradlew.bat test buildPlugin

Готовый ZIP появится в dbml-intellij-plugin/build/distributions/. Его можно установить через Settings → Plugins → Install Plugin from Disk…, после чего перезапустить IDE и открыть .dbml-файл.

Для разработки доступен запуск отдельной тестовой IDE командой ./gradlew runIde или .\gradlew.bat runIde в PowerShell.

Планируем интеграцию с dbdiagram.io

Одно из направлений развития — интеграция с dbdiagram.io прямо через плагин. Она нужна для нашего рабочего процесса: общую схему проектируем совместно в сервисе, а локальные правки удобнее готовить рядом с кодом в IntelliJ IDEA.

Планируем добавить возможность публиковать изменённую DBML-схему в dbdiagram.io из плагина. Хотим связать локальную работу разработчика с общей схемой команды и сократить ручной перенос изменений между IDE и сервисом.

Целевой сценарий такой:

1. Команда проектирует и обсуждает схему в dbdiagram.io.

2. Разработчик вносит локальные изменения в .dbml в IntelliJ IDEA и проверяет их в превью.

3. Когда правки готовы к передаче команде, публикует изменённую схему в dbdiagram.io через плагин.

4. Коллеги продолжают совместную работу с обновлённой схемой в привычном сервисе.

В версии 0.1.0 этой интеграции ещё нет. Публикация будет отдельной сетевой операцией; локальное редактирование и построение превью уже работают офлайн. Детали интеграции и взаимодействия с параллельными правками команды будем прорабатывать при её реализации.

Куда планируем развивать DBML Diagram

Помимо интеграции с dbdiagram.io, планируем развивать возможности, обозначенные в roadmap проекта. Сроки и порядок реализации пока открыты.

Поддержка языка внутри IDE. Одно из направлений — модель DBML на базе PSI. Она даст основу для автодополнения, навигации по таблицам и полям, а затем и рефакторинга. Например, хочется переименовывать поле с учётом ссылок на него.

Более удобная работа с расположением таблиц. Здесь интересны интеграция другого движка раскладки, например ELK, и сохранение вручную заданных позиций. Это должно помочь при работе со схемами, для которых автоматического размещения недостаточно.

Визуальное редактирование. Возможность менять схему через диаграмму потребует синхронизации с DBML-текстом. Хочется сохранить понятный результат в файле, который можно проверить и закоммитить.

История схемы и семантическое сравнение. В перспективе — работа с Git-историей и сравнение схем на уровне модели: какие таблицы и поля добавлены, что удалено, какие типы или связи изменились. Такой режим мог бы дополнить просмотр текстового diff при обсуждении изменений базы.

Приоритеты хотим определять на основе реальных сценариев использования. Если вам важнее публикация локальных правок в dbdiagram.io, навигация по большой схеме, удобная раскладка или сравнение двух версий, расскажите, какую задачу это поможет решить.

Приглашаем к участию в разработке

DBML Diagram распространяется с открытым исходным кодом под лицензией Apache 2.0. Можно изучать реализацию, пробовать плагин на своих проектах и предлагать изменения.

Особенно полезны три вида обратной связи:

• Схема, которая разбирается или отображается неправильно. Для воспроизведения пригодится небольшой DBML-пример, версия IDE и плагина, описание ожидаемого результата и скриншот фактического поведения.

• Предложение новой возможности. Расскажите, какой задачи сейчас не хватает в вашем процессе работы и как вы решаете её вручную. Это поможет обсудить вариант реализации и приоритет.

• Вклад в проект. Приветствуются pull request с исправлениями, тестами, улучшениями документации, парсера и визуализации.

Ошибки и предложения можно оставлять в GitHub Issues. Перед отправкой примера уберите из него закрытые названия, данные и другую внутреннюю информацию проекта. Для участия в разработке есть CONTRIBUTING.md: там описаны запуск окружения и проверки перед pull request.

Будем рады и обсуждению здесь, в комментариях. Используете ли вы dbdiagram.io для совместного проектирования? Как сейчас переносите локальные изменения в общую схему и что было бы полезно при публикации прямо из IntelliJ IDEA?

За развитием плагина и другими материалами по Java и backend-разработке можно следить в Boost for Java.

По личным вопросам и предложениям о сотрудничестве пишите напрямую: @v_d_roman.

Попробовать DBML Diagram · Посмотреть код и предложить изменения