Подключение к 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 или новее.

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

Плагин можно установить двумя способами:

• Через URL P2-репозитория (рекомендуется): DBeaver загружает плагин из облачного хранилища и запоминает источник для последующих автоматических обновлений.
• Из ZIP-архива (GitHub Releases): скачайте архив и установите через локальный файл. Подходит для сетей, где внешние Eclipse-репозитории недоступны, или для воспроизводимой установки конкретной версии. Автоматические обновления при этом способе не поддерживаются.

Установка через URL P2-репозитория

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 загрузит метаданные репозитория.

   Скриншот

   

   Важно

   В процессе установки DBeaver скачивает не только сам плагин, но и его зависимости (OSGi-компоненты) с серверов проекта Eclipse и других внешних репозиториев. Если эти ресурсы недоступны из вашей сети, обратитесь к сетевому администратору или воспользуйтесь установкой из ZIP-архива.

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. После перезапуска плагин станет активным.

Установка из ZIP-архива (GitHub Releases)

1. Перейдите на страницу GitHub Releases и скачайте файл ydb-dbeaver-plugin-*.zip нужной версии.

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

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

4. В открывшемся окне Add Repository нажмите Archive..., укажите путь к скачанному ZIP-файлу и нажмите Add.

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

   Важно

   Перед нажатием Next > снимите флаг Contact all update sites during install to find required software в нижней части окна Install New Software. Если этот флаг включён, DBeaver при расчёте зависимостей обращается ко всем зарегистрированным P2-репозиториям (dbeaver.io, eclipse.org и другим), и при их недоступности или медленных ответах диалог установки зависает на этапе Calculating requirements and dependencies. Плагин использует только компоненты DBeaver, уже установленные локально, поэтому обращение к другим репозиториям при установке не требуется.

6. Нажмите Next >.

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

8. DBeaver может показать предупреждение о неподписанном содержимом. Нажмите Install Anyway.

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

10. 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 дополнительно показывает статистику выполнения (количество строк, время выполнения).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Автоматические обновления поддерживаются только при установке через URL P2-репозитория. DBeaver запоминает источник (URL репозитория) и при публикации новой версии предлагает обновление одним из двух способов:

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

При установке из ZIP-архива обновление выполняется вручную: скачайте новый архив со страницы GitHub Releases, откройте Help → Installation Information, выберите плагин, нажмите Uninstall, затем установите новую версию заново.