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

Visual Studio Code — бесплатный кроссплатформенный редактор кода с открытым исходным кодом, поддерживающий широкую экосистему расширений для работы с базами данных, языковых серверов и инструментов разработки.

YDB for VS Code — расширение VS Code с нативной поддержкой YDB. Плагин предоставляет специализированный интерфейс для работы с объектами YDB: иерархический навигатор таблиц, топиков, представлений, внешних источников данных, поддержку всех способов аутентификации, редактор YQL с подсветкой синтаксиса, визуализацию планов выполнения, мониторинг сессий и кластера, управление правами доступа (ACL), встроенный MCP-сервер для AI-ассистентов и другие возможности.

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

• Подключение к YDB со всеми способами аутентификации: анонимная, статическая, по токену, по сервисному аккаунту, по метаданным.
• Иерархический навигатор объектов: таблицы (строковые и колоночные), топики, представления, внешние источники данных, внешние таблицы, трансферы, потоковые запросы.
• Системные объекты: системные представления (.sys), пулы ресурсов.
• Редактор YQL с подсветкой синтаксиса, автодополнением таблиц и колонок.
• Выполнение запросов и визуализация результатов: таблица, JSON, диаграмма.
• Визуализация плана выполнения запроса (EXPLAIN).
• Мониторинг активных сессий через .sys/query_sessions.
• Дашборд кластера на базе YDB Embedded UI: загрузка CPU, использование памяти, сетевой трафик (обновление каждые 10 секунд).
• Управление правами доступа (ACL): просмотр разрешений на объекты базы данных.
• Генерация DDL-скриптов (CREATE) для любого объекта базы данных.
• Управление потоковыми запросами: просмотр, запуск, остановка.
• Конвертер SQL-запросов из других диалектов (PostgreSQL, MySQL, ClickHouse и других) в YQL.
• Встроенный MCP-сервер — прямой доступ к базам данных из AI-ассистентов (Claude Code и других).
• Семантический поиск по документации YQL (RAG) для AI-assisted написания запросов.

Требования

Для работы плагина требуется Visual Studio Code версии 1.75.0 или новее.

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

Плагин можно установить из VS Code Marketplace или из .vsix-файла на странице GitHub Releases.

Установка из VS Code Marketplace

1. Откройте панель расширений в VS Code (Ctrl+Shift+X / Cmd+Shift+X).
2. В строке поиска введите YDB for VS Code и выберите расширение от издателя ydb-tech (прямая ссылка).
3. Нажмите Install.

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

code --install-extension ydb-tech.ydb-vscode-plugin

Установка из VSIX-файла

Способ подходит, если нужна конкретная версия или нет доступа к Marketplace.

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

2. Установите расширение одним из способов:

   • Через терминал:

     code --install-extension ydb-vscode-plugin-X.X.X.vsix
     

     Где X.X.X — номер скачанной версии.

   • Через интерфейс VS Code:

     1. Откройте панель расширений (Ctrl+Shift+X / Cmd+Shift+X).
     2. Нажмите ... (три точки) в правом верхнем углу панели.
     3. Выберите Install from VSIX....
     4. Укажите путь к скачанному .vsix-файлу.

После установки любым из способов перезагрузите VS Code. В панели Activity Bar появится значок YDB.

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

1. Нажмите на значок YDB в Activity Bar слева.

2. В панели Connections нажмите кнопку Add Connection (значок +).

3. Откроется форма создания подключения. Заполните поля:

   Поле	Описание	Пример
   Connection Name	Произвольное имя подключения	my-ydb
   Host	Хост эндпойнта кластера YDB	ydb.example.com
   Port	Порт (по умолчанию 2135)	2135
   Database	Путь к базе данных	/Root/database
   Monitoring URL	URL YDB Embedded UI, используется для дашборда (заполняется автоматически по хосту, можно переопределить)	http://ydb.example.com:8765
   Secure connection (grpcs)	Использовать защищённое соединение (grpcs://)	☑
   Use RAG	Включить поиск по документации YQL для данного подключения	☑

4. При необходимости укажите путь к пользовательскому CA-сертификату (PEM) в поле CA Certificate File — для подключений с нестандартным TLS. Если поле не заполнено, используется встроенный сертификат Yandex Cloud.

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

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

7. Нажмите Save. Подключение появится в панели Connections.

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

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

Anonymous

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

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

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

Access Token

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

Service Account Key File

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

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

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

Metadata Service

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

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

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

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

Правый клик на любом объекте в навигаторе открывает контекстное меню с доступными действиями.

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

Рабочее пространство запросов

Откройте рабочее пространство запросов через Ctrl+Shift+Q (Cmd+Shift+Q на macOS) или нажмите Open Query Workspace в контекстном меню подключения. В рабочем пространстве можно писать и выполнять YQL-запросы, просматривать историю и результаты.

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

• Show Preview — SELECT первых 100 строк.
• Make Query — SELECT с именем объекта.

Редактор YQL

Редактор поддерживает:

• Подсветку синтаксиса YQL: ключевые слова, типы данных, встроенные функции.
• Автодополнение имён таблиц и колонок (по схеме подключённой базы данных).
• Выполнение запроса: Ctrl+Enter (Cmd+Enter на macOS).

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

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

Результаты выполнения отображаются в панели Results в виде таблицы, JSON или диаграммы (переключение вкладками).

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

Выберите Explain YQL Query в контекстном меню редактора или в командной палитре (Ctrl+Shift+P), чтобы получить план выполнения запроса. Плагин отображает дерево операций плана в текстовом виде.

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

В панели Sessions (Activity Bar → YDB) отображаются все активные сессии с текущим запросом, состоянием и длительностью (данные из системного представления .sys/query_sessions). Кнопка Toggle Hide Idle скрывает сессии без активного запроса.

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

В панели Database Load (Activity Bar → YDB) отображается нагрузка на кластер в реальном времени (обновление каждые 10 секунд):

• Загрузка CPU (% и количество ядер).
• Использование памяти (% и объём).
• Сетевой трафик.

Потоковые запросы

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

• Просмотр исходного YQL (View Source).
• Запуск и остановка (Start / Stop).

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

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

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

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

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

Просмотр разрешений

Кликните правой кнопкой по объекту в навигаторе и выберите View Permissions для просмотра прав доступа (ACL), назначенных на этот объект.

Генерация DDL

Кликните правой кнопкой по таблице, топику или другому объекту в навигаторе и выберите Create DDL для получения CREATE-скрипта объекта.

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

Кликните правой кнопкой по соответствующей папке в навигаторе, чтобы создать новый объект:

• New Row Table / New Column Table — создать строковую или колоночную таблицу.
• New Topic — создать топик.
• New View — создать представление.
• New Object Storage Data Source / New YDB Data Source — создать внешний источник данных.
• New CSV/JSON/Parquet External Table — создать внешнюю таблицу.
• New Transfer — создать трансфер.
• New Streaming Query — создать потоковый запрос.

Интеграция с AI-ассистентами (MCP)

Плагин запускает встроенный MCP-сервер (Model Context Protocol), который позволяет AI-ассистентам (Claude Code и другим) напрямую выполнять запросы к базам данных YDB, настроенным в плагине.

Настройка порта

Сервер запускается на порту 3333 (только localhost) по умолчанию. Изменить порт можно в настройках VS Code:

{
  "ydb.mcpPort": 3333
}

Если порт уже занят, расширение покажет предупреждение и продолжит работу без MCP.

Подключение Claude Code

1. Убедитесь, что расширение YDB запущено в VS Code и в панели Connections добавлено хотя бы одно подключение (см. Создание подключения).

2. Зарегистрируйте MCP-сервер в Claude Code глобально для текущего пользователя:

   claude mcp add --scope user --transport sse ydb http://localhost:3333/sse
   

   Флаг --scope user сохраняет конфигурацию глобально — сервер будет доступен из любого каталога, в котором запускается Claude Code. Без этого флага используется scope local (по умолчанию), и регистрацию придётся повторять для каждого проекта.

3. Проверьте подключение:

   claude mcp list
   

Доступные MCP-инструменты

Параметр connection — имя подключения, как оно отображается в панели Connections.

Поиск по документации YQL (RAG)

Плагин поддерживает семантический и ключевой поиск по документации YQL с помощью встроенного RAG-индекса (Retrieval-Augmented Generation). Это позволяет AI-ассистентам (через инструмент ydb_yql_help) находить релевантные фрагменты синтаксического справочника при написании запросов.

Включение RAG

1. При создании или редактировании подключения установите флаг Use RAG.
2. Плагин автоматически определит версию YDB и загрузит соответствующий индекс из облака при первом подключении.

Режимы поиска

• Ключевой поиск (keyword) — работает без дополнительных зависимостей, используется по умолчанию.
• Семантический поиск (vector) — требует локально запущенного Ollama с моделью эмбеддингов nomic-embed-text. См. Установка Ollama и модели эмбеддингов.

Статус RAG (Running / Not running) и статус Ollama отображаются прямо в форме подключения.

Установка Ollama и модели эмбеддингов

Ollama — локальный сервер для запуска языковых моделей и моделей эмбеддингов. Плагин обращается к нему по HTTP, чтобы преобразовывать тексты документации и поисковые запросы в векторы для семантического поиска.

1. Установите Ollama по инструкции на официальной странице загрузки (поддерживаются macOS, Windows и Linux).

2. Убедитесь, что сервис Ollama запущен и доступен на http://localhost:11434:

   curl http://localhost:11434/api/tags
   

   Ответ в формате JSON со списком моделей означает, что сервис работает.

3. Скачайте модель эмбеддингов nomic-embed-text (~270 МБ):

   ollama pull nomic-embed-text
   

4. Убедитесь, что модель доступна:

   ollama list
   

   В выводе должна появиться строка nomic-embed-text.

5. Откройте форму подключения в плагине и убедитесь, что статус Ollama отображается как Running. Если статус Not running — проверьте, что сервис Ollama запущен и доступен на http://localhost:11434.

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

Способ обновления зависит от того, как был установлен плагин.

Обновление из VS Code Marketplace

Если плагин установлен из Marketplace, VS Code обновляет его автоматически.

Чтобы обновить плагин вручную:

1. Откройте панель расширений (Ctrl+Shift+X / Cmd+Shift+X).
2. В строке поиска введите YDB for VS Code и откройте установленное расширение.
3. Если доступна новая версия, появится кнопка Update — нажмите её.

Обновление из VSIX-файла

Если плагин установлен из VSIX-файла, автоматическое обновление недоступно — VS Code не отслеживает обновления для расширений, установленных вручную.

1. Скачайте новый .vsix-файл со страницы GitHub Releases.
2. Установите его поверх старой версии тем же способом, что и при первой установке — VS Code автоматически заменит предыдущую версию.