Connecting to YDB Using the DBeaver Plugin

DBeaver is a free cross-platform open-source database management tool that provides a visual interface for connecting to various databases and executing SQL queries.

YDB DBeaver Plugin is a DBeaver extension with native support for YDB. Unlike connecting via a JDBC driver, the plugin provides a specialized interface for working with YDB objects: a hierarchical navigator for tables, topics, views, external data sources, support for all authentication methods, a YQL editor, query execution plan visualization, session and cluster monitoring, access control (ACL) management, and other features.

Key Features of the Plugin

• Connecting to YDB with all authentication methods: anonymous, static, token-based, service account, metadata-based.
• Hierarchical object navigator: tables, topics, external data sources, external tables, views.
• System objects: system views (.sys), resource pools, and resource pool classifiers.
• YQL editor with syntax highlighting for over 150 keywords and built-in functions.
• Visualization of the query execution plan (EXPLAIN / EXPLAIN ANALYZE).
• Monitoring of active sessions via .sys/query_sessions.
• Cluster dashboard: CPU load, disk usage, memory usage, network traffic, node status (updated every 5 seconds).
• Access control (ACL) management: granting, revoking, and viewing permissions.
• Management of streaming queries: viewing, modifying, starting, stopping.
• Federated queries via external data sources (S3, databases).
• SQL Dialect Converter from other dialects (PostgreSQL, MySQL, ClickHouse, etc.) to YQL.
• Specialized editors for JSON, JSONDOCUMENT, YSON data types.

Requirements

The plugin requires DBeaver Community Edition version 24.x or later.

Installing the Plugin

The plugin is installed via DBeaver's extension installation mechanism from a URL repository, which ensures automatic updates.

1. Open DBeaver. In the top menu, select Help → Install New Software....

   Screenshot

   

2. Click the Add... button to the right of the Work with: field.

   Screenshot

   

3. In the Add Repository window that opens, specify a repository name (for example, YDB Plugin) and paste the following URL into the Location field:

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

   Click Add. DBeaver will load the repository metadata.

   Screenshot

   

4. The DBeaver YDB Support category will appear in the component list. Select it and click Next >.

   Screenshot

   

5. On the Install Details screen, make sure both components (org.jkiss.dbeaver.ext.ydb and org.jkiss.dbeaver.ext.ydb.ui) are listed, then click Next >.

   Screenshot

   

6. DBeaver may display a warning about unsigned content. This is expected behavior — the plugin's JAR files are not signed with a commercial certificate. Click Install Anyway.

   Note

   Eclipse, on which DBeaver is based, checks JAR file signatures to verify authenticity. This open-source plugin is distributed without a signature; the source code is available in the repository.

7. Review the license (Apache License 2.0), select I accept the terms of the license agreements, and click Finish.

   Screenshot

   

8. DBeaver will install the plugin and prompt you to restart. Click Restart Now. After restarting, the plugin will become active.

Creating a Connection to YDB

To create a connection to YDB, follow these steps:

1. In the top menu, select Database → New Database Connection (or press Ctrl+Shift+N).

2. In the search field, type YDB. Select YDB from the list and click Next.

3. The YDB connection setup page will open. Fill in the fields:

   Field	Description	Example
   Host	Host of the endpoint for the YDB cluster	ydb.example.com
   Port	Port (default is 2135)	2135
   Database	Path to the database	/Root/database
   Monitoring URL	URL of the YDB Embedded UI with the database path, used for the dashboard (optional)	http://ydb.example.com:8765/monitoring/tenant?name=%2FRoot%2Fdatabase
   Use secure connection	Use a secure connection (grpcs://)	☑
   Enable autocomplete API	Autocomplete via YDB API	☑

4. Select an authentication method from the Auth type dropdown list (see Authentication Methods).

5. Click the Test Connection button to verify the settings. If the connection is successful, a dialog will appear with the connection time in milliseconds.

6. Click the Finish button. The connection will appear in the Database Navigator panel.

Authentication Methods

The plugin supports all authentication methods available in YDB. The method is selected from the Auth type dropdown list on the connection setup page.

Anonymous

Connection without credentials. Used for local or test installations of YDB. No additional fields need to be filled out.

Static (Username and Password)

Authentication using a username and password. Enter the username in the User field and the password in the Password field. Used if YDB server has username and password authentication enabled.

Token

Authentication using an IAM or OAuth token. Enter the token in the Token field. The token is passed in the header of each request.

Service Account

Authentication using the key of a Yandex Cloud service account. Specify the path to the JSON file with the key in the SA Key File field (use the ... button to select the file). For more information on how to create an authorized key, see the Yandex Cloud documentation.

Key file format:

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

Metadata

Authentication via the Yandex Cloud metadata service. The plugin obtains an IAM token from the virtual machine's metadata service. Used only when DBeaver is running on a Yandex Cloud virtual machine.

Object Navigator

After connecting, the YDB object hierarchy is displayed in the Database Navigator panel. The root node is the connection, and inside it is the database path, which contains the following folders:

• Tables — tables organized by subdirectories according to the path in YDB (for example, a table with the path folder1/subfolder/mytable will be nested under folder1 → subfolder).
• Topics — topics.
• Views — views.
• External Data Sources — external data sources.
• External Tables — external tables.
• System Views (.sys) — system views, such as partition_stats, query_sessions.
• Resource Pools — resource pools.

Working with the Plugin

YQL Editor

Open the SQL Editor (F3 or double-click on the connection). The editor supports:

• Syntax highlighting for YQL: keywords (UPSERT, REPLACE, EVALUATE, PRAGMA, WINDOW, and 145+ others), data types, built-in functions.
• Autocompletion of table, column, and function names.
• Query execution: Ctrl+Enter for the current query, Ctrl+Shift+Enter for the entire script.

Example YQL query:

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

EXPLAIN and Execution Plan

Click Explain (or Ctrl+Shift+E) to get the query execution plan. The plugin displays:

• Text plan — a tree of operations in text form.
• Diagram — a graphical representation as a DAG.
• SVG plan — an interactive visualization.

EXPLAIN ANALYZE additionally shows execution statistics (number of rows, execution time).

Session Manager

Right-click on the connection and select Manage Sessions, or use the Database → Manage Sessions menu item. The opened view displays all active sessions with the current query, state, and duration (data from the system view .sys/query_sessions). The Hide Idle checkbox hides sessions without an active query.

Cluster Dashboard

Open the Dashboard tab in the connection editor (requires the Monitoring URL field to be filled in during connection setup).

The dashboard displays real-time data (updated every 5 seconds):

• CPU load by nodes.
• Disk space usage.
• Memory usage.
• Network traffic.
• Number of executing queries.
• Status of cluster nodes.

Streaming Queries

In the navigator, expand the Streaming Queries folder. For each query, you can:

• View the original YQL.
• View errors (issues).
• View the execution plan.
• Perform actions: Start, Stop, Alter.

SQL Dialect Converter

The plugin allows you to convert an SQL query written in another dialect (PostgreSQL, MySQL, ClickHouse, etc.) to YQL. The converter is available on the Convert Dialect tab in the connection editor.

To convert a query:

1. In the Source Dialect dropdown list, select the source SQL dialect. The list of dialects is requested from the plugin's external service when the tab is first opened.
2. Paste the source SQL code into the Input SQL field.
3. Click Convert. The result will appear in the lower field.
4. Click Copy to copy the result to the clipboard.

For more information on how the converter works, supported dialects, and limitations, see the SQL Dialect Converter to YQL article.

Creating Objects

Right-click on a folder or object and select Create New:

• Create Table — create a new table.
• Create Topic — create a new topic.
• Create Resource Pool — create a resource pool.

Updating the Plugin

DBeaver uses the Eclipse P2 mechanism to detect and install updates. When you install the plugin, DBeaver remembers the source — the repository URL. When a new version is published, DBeaver compares the installed version with the version in the repository and offers an update in one of two ways:

1. Automatically on the next DBeaver startup (if update checks are enabled in Window → Preferences → Install/Update → Automatic Updates).
2. Manually via Help → Check for Updates: select the available update and follow the same steps as during the initial installation (license → warning about unsigned content → restart).