Подключение к YDB с помощью плагина DBeaver

DBeaver — бесплатный кроссплатформенный инструмент управления базами данных с открытым исходным кодом, обеспечивающий визуальный интерфейс для подключения к различным базам данных и выполнения SQL-запросов.

YDB DBeaver Plugin — расширение DBeaver с нативной поддержкой YDB. В отличие от подключения через JDBC-драйвер, плагин предоставляет специализированный интерфейс для работы с объектами YDB: иерархический навигатор таблиц, топиков, представлений, внешних источников данных, поддержку всех способов аутентификации, редактор YQL, визуализацию планов выполнения, мониторинг сессий и кластера, управление правами доступа (ACL) и другие возможности.

Ключевые возможности плагина

• Подключение к YDB со всеми способами аутентификации: анонимная, статическая, по токену, по сервисному аккаунту, по метаданным.
• Иерархический навигатор объектов: таблицы, топики, внешние источники данных, внешние таблицы, представления.
• Системные объекты: системные представления (.sys), пулы ресурсов и классификаторы пулов ресурсов.
• Редактор YQL с подсветкой 150+ ключевых слов и встроенных функций.
• Визуализация плана выполнения запроса (EXPLAIN / EXPLAIN ANALYZE).
• Мониторинг активных сессий через .sys/query_sessions.
• Дашборд кластера: загрузка CPU, использование дисков, памяти, сетевой трафик, статус узлов (обновление каждые 5 секунд).
• Управление правами доступа (ACL): выдача, отзыв, просмотр разрешений.
• Управление потоковыми запросами: просмотр, изменение, запуск, остановка.
• Федеративные запросы через внешние источники данных (S3, базы данных).
• Конвертер SQL-запросов из других диалектов (PostgreSQL, MySQL, ClickHouse и других) в YQL.
• Специализированные редакторы для типов данных JSON, JSONDOCUMENT, YSON.

Требования

Для работы плагина требуется DBeaver Community Edition версии 24.x или новее.

Установка плагина

Плагин устанавливается через механизм установки расширений DBeaver из URL-репозитория, что обеспечивает автоматическое получение обновлений.

1. Откройте DBeaver. В верхнем меню выберите Help → Install New Software....

   Скриншот

   

2. Нажмите кнопку Add... справа от поля Work with:.

   Скриншот

   

3. В открывшемся окне Add Repository укажите имя репозитория (например, YDB Plugin) и вставьте в поле Location следующий URL:

   https://storage.yandexcloud.net/ydb-dbeaver-plugin
   

   Нажмите Add. DBeaver загрузит метаданные репозитория.

   Скриншот

   

4. В списке компонентов появится категория DBeaver YDB Support. Отметьте её и нажмите Next >.

   Скриншот

   

5. На экране Install Details убедитесь, что в списке присутствуют оба компонента (org.jkiss.dbeaver.ext.ydb и org.jkiss.dbeaver.ext.ydb.ui), и нажмите Next >.

   Скриншот

   

6. DBeaver может показать предупреждение о неподписанном содержимом. Это ожидаемое поведение — JAR-файлы плагина не подписаны коммерческим сертификатом. Нажмите Install Anyway.

   Примечание

   Eclipse, на котором основан DBeaver, проверяет подписи JAR-файлов для подтверждения подлинности. Этот плагин с открытым исходным кодом распространяется без подписи, исходный код доступен в репозитории.

7. Ознакомьтесь с лицензией (Apache License 2.0), выберите I accept the terms of the license agreements и нажмите Finish.

   Скриншот

   

8. DBeaver установит плагин и предложит перезапуск. Нажмите Restart Now. После перезапуска плагин станет активным.

Создание подключения к YDB

Для создания подключения к YDB выполните следующие шаги:

1. В верхнем меню выберите Database → New Database Connection (или нажмите Ctrl+Shift+N).

2. В поле поиска введите YDB. Выберите YDB из списка и нажмите Next.

3. Откроется страница настройки подключения к YDB. Заполните поля:

   Поле	Описание	Пример
   Host	Хост эндпойнта кластера YDB	ydb.example.com
   Port	Порт (по умолчанию 2135)	2135
   Database	Путь к базе данных	/Root/database
   Monitoring URL	URL YDB Embedded UI с путём к базе данных, используется для дашборда (необязательно)	http://ydb.example.com:8765/monitoring/tenant?name=%2FRoot%2Fdatabase
   Use secure connection	Использовать защищённое соединение (grpcs://)	☑
   Enable autocomplete API	Автодополнение через API YDB	☑

4. Выберите способ аутентификации в выпадающем списке Auth type (см. Способы аутентификации).

5. Нажмите кнопку Test Connection для проверки настроек. При успешном подключении появится диалог с временем соединения в миллисекундах.

6. Нажмите кнопку Finish. Подключение появится в панели Database Navigator.

Способы аутентификации

Плагин поддерживает все способы аутентификации, доступные в YDB. Способ выбирается в выпадающем списке Auth type на странице настройки подключения.

Anonymous

Подключение без учётных данных. Используется для локальных или тестовых установок YDB. Дополнительных полей заполнять не требуется.

Static (логин и пароль)

Аутентификация по логину и паролю. Укажите имя пользователя в поле User и пароль в поле Password. Используется, если на сервере YDB включена аутентификация по логину и паролю.

Token

Аутентификация по IAM- или OAuth-токену. Введите токен в поле Token. Токен передаётся в заголовке каждого запроса.

Service Account

Аутентификация по ключу сервисного аккаунта Yandex Cloud. Укажите путь к JSON-файлу с ключом в поле SA Key File (для выбора файла используйте кнопку ...). Подробнее о том, как создать авторизованный ключ, см. в документации Yandex Cloud.

Формат файла ключа:

{
  "id": "aje...",
  "service_account_id": "aje...",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----\n..."
}

Metadata

Аутентификация через сервис метаданных Yandex Cloud. Плагин получает IAM-токен от сервиса метаданных виртуальной машины. Используется, только когда DBeaver запущен на виртуальной машине Yandex Cloud.

Навигатор объектов

После подключения в панели Database Navigator отображается иерархия объектов YDB. Корневой узел — подключение, внутри — путь к базе данных, который содержит следующие папки:

• Tables — таблицы, организованные по поддиректориям согласно пути в YDB (например, таблица по пути folder1/subfolder/mytable будет вложена в folder1 → subfolder).
• Topics — топики.
• Views — представления.
• External Data Sources — внешние источники данных.
• External Tables — внешние таблицы.
• System Views (.sys) — системные представления, такие как partition_stats, query_sessions.
• Resource Pools — пулы ресурсов.

Работа с плагином

Редактор YQL

Откройте SQL Editor (F3 или двойной клик по подключению). Редактор поддерживает:

• Подсветку синтаксиса YQL: ключевые слова (UPSERT, REPLACE, EVALUATE, PRAGMA, WINDOW и 145+ других), типы данных, встроенные функции.
• Автодополнение имён таблиц, колонок и функций.
• Выполнение запросов: Ctrl+Enter — текущий запрос, Ctrl+Shift+Enter — весь скрипт.

Пример YQL-запроса:

UPSERT INTO `users` (id, name, created_at)
VALUES (1, "Alice", CurrentUtcDatetime());

EXPLAIN и план выполнения

Нажмите Explain (или Ctrl+Shift+E), чтобы получить план выполнения запроса. Плагин отображает:

• Text plan — дерево операций в текстовом виде.
• Diagram — графическое представление в виде DAG.
• SVG plan — интерактивная визуализация.

EXPLAIN ANALYZE дополнительно показывает статистику выполнения (количество строк, время выполнения).

Менеджер сессий

Кликните правой кнопкой по подключению и выберите Manage Sessions, либо используйте пункт меню Database → Manage Sessions. В открывшемся представлении отображаются все активные сессии с текущим запросом, состоянием и длительностью (данные из системного представления .sys/query_sessions). Галочка Hide Idle скрывает сессии без активного запроса.

Дашборд кластера

Откройте вкладку Dashboard в редакторе подключения (требует заполненного поля Monitoring URL при настройке подключения).

Дашборд отображает в реальном времени (обновление каждые 5 секунд):

• Загрузку CPU по узлам.
• Использование дискового пространства.
• Использование памяти.
• Сетевой трафик.
• Количество выполняющихся запросов.
• Статус узлов кластера.

Стриминговые запросы

В навигаторе раскройте папку Streaming Queries. Для каждого запроса доступны:

• Просмотр исходного YQL.
• Просмотр ошибок (issues).
• Просмотр плана выполнения.
• Действия: Start, Stop, Alter.

Конвертер SQL-диалектов

Плагин позволяет преобразовать SQL-запрос, написанный на другом диалекте (PostgreSQL, MySQL, ClickHouse и других), в YQL. Конвертер доступен на вкладке Convert Dialect в редакторе подключения.

Чтобы преобразовать запрос:

1. В выпадающем списке Source Dialect выберите исходный диалект SQL. Список диалектов запрашивается с внешнего сервиса плагина при первом открытии вкладки.
2. Вставьте исходный SQL-код в поле Input SQL.
3. Нажмите Convert. Результат появится в нижнем поле.
4. Нажмите Copy, чтобы скопировать результат в буфер обмена.

Подробнее о принципах работы конвертера, поддерживаемых диалектах и ограничениях см. в статье Конвертер SQL-диалектов в YQL.

Создание объектов

Кликните правой кнопкой по папке или объекту и выберите Create New:

• Create Table — создать новую таблицу.
• Create Topic — создать новый топик.
• Create Resource Pool — создать пул ресурсов.

Обновление плагина

DBeaver использует механизм Eclipse P2 для обнаружения и установки обновлений. При установке плагина DBeaver запоминает источник — URL репозитория. Когда публикуется новая версия, DBeaver сравнивает установленную версию с версией в репозитории и предлагает обновление одним из двух способов:

1. Автоматически при следующем запуске DBeaver (если включена проверка обновлений в Window → Preferences → Install/Update → Automatic Updates).
2. Вручную через Help → Check for Updates: выберите доступное обновление и пройдите те же шаги, что и при первой установке (лицензия → предупреждение о неподписанном содержимом → перезапуск).