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, 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, and metadata.
• 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 150+ keywords and built-in functions.
• Query execution plan visualization (EXPLAIN / EXPLAIN ANALYZE).
• Active session monitoring via .sys/query_sessions.
• Cluster dashboard: CPU load, disk usage, memory usage, network traffic, node status (updates every 5 seconds).
• Access control (ACL) management: granting, revoking, and viewing permissions.
• Streaming query management: viewing, modifying, starting, and stopping.
• Federated queries via external data sources (S3, databases).
• SQL query converter from other dialects (PostgreSQL, MySQL, ClickHouse, and others) to YQL.
• Specialized editors for JSON, JSONDOCUMENT, and YSON data types.

Requirements

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

Installing the plugin

The plugin can be installed in two ways:

• Via P2 repository URL (recommended): DBeaver downloads the plugin from cloud storage and remembers the source for subsequent automatic updates.
• From a ZIP archive (GitHub Releases): download the archive and install via a local file. Suitable for networks where external Eclipse repositories are unavailable, or for reproducible installation of a specific version. Automatic updates are not supported with this method.

Installation via P2 repository URL

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 (e.g., 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

   

   Warning

   During installation, DBeaver downloads not only the plugin itself but also its dependencies (OSGi components) from Eclipse project servers and other external repositories. If these resources are not accessible from your network, contact your network administrator or use installation from a ZIP archive.

4. A category DBeaver YDB Support will appear in the component list. Check 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 in the list, and click Next >.

   Screenshot

   

6. DBeaver may show 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, verifies JAR file signatures to confirm 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 restart, the plugin will be active.

Installation from a ZIP archive (GitHub Releases)

1. Go to the GitHub Releases page and download the ydb-dbeaver-plugin-*.zip file of the required version.

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

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

4. In the Add Repository window that opens, click Archive..., specify the path to the downloaded ZIP file, and click Add.

5. The DBeaver YDB Support category will appear in the component list. Check it.

   Warning

   Before clicking Next >, uncheck the Contact all update sites during install to find required software checkbox at the bottom of the Install New Software window. If this checkbox is enabled, DBeaver contacts all registered P2 repositories (dbeaver.io, eclipse.org, and others) when calculating dependencies, and if they are unavailable or respond slowly, the installation dialog hangs at the Calculating requirements and dependencies step. The plugin only uses DBeaver components already installed locally, so contacting other repositories during installation is not required.

6. Click Next >.

7. On the Install Details screen, make sure both components (org.jkiss.dbeaver.ext.ydb and org.jkiss.dbeaver.ext.ydb.ui) are present in the list, and click Next >.

8. DBeaver may show a warning about unsigned content. Click Install Anyway.

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

10. DBeaver will install the plugin and prompt you to restart. Click Restart Now. After the restart, the plugin becomes 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, enter YDB. Select YDB from the list and click Next.

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

   Field	Description	Example
   Host	Host of the YDB cluster endpoint	ydb.example.com
   Port	Port (default 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 the authentication method from the Auth type drop-down list (see Authentication methods).

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

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 drop-down list on the connection settings page.

Anonymous

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

Static (login and password)

Authentication by login and password. Enter the username in the User field and the password in the Password field. on the YDB server. Used if login and password authentication is enabled

Token

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

Service Account

Authentication by a service account key of Yandex Cloud. 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 Yandex Cloud Metadata Service. The plugin obtains an IAM token from the virtual machine metadata service. It is used only when DBeaver is running on a Yandex Cloud virtual machine.

Object navigator

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

• Tables — tables organized into subdirectories according to the path in YDB (for example, a table at path folder1/subfolder/mytable will be nested in 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 the connection). The editor supports:

• Syntax highlighting for YQL: keywords (UPSERT, REPLACE, EVALUATE, PRAGMA, WINDOW and 145+ others), data types, built-in functions.
• Auto-completion of table names, columns, and functions.
• Query execution: Ctrl+Enter — current query, Ctrl+Shift+Enter — 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 — operation tree in text form.
• Diagram — graphical representation as a DAG.
• SVG plan — interactive visualization.

EXPLAIN ANALYZE additionally shows execution statistics (row count, execution time).

Session manager

Select the menu item Tools → Sessions Manager, or right-click the connection and select the corresponding 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 when configuring the connection).

The dashboard displays in real time (updates every 5 seconds):

• CPU load by node.
• Disk space usage.
• Memory usage.
• Network traffic.
• Number of running queries.
• Cluster node status.

Streaming queries

In the navigator, expand the Streaming Queries folder. For each query, the following are available:

• View the source YQL.
• View errors (issues).
• View the execution plan.
• Actions: Start, Stop, Alter.

SQL dialect converter

The plugin allows you to convert an SQL query written in another dialect (PostgreSQL, MySQL, ClickHouse, and others) to YQL. The converter is available in the context menu Tools → Convert Dialect in the connection editor.

To convert a query:

1. In the Source Dialect dropdown, select the source SQL dialect. The list of dialects is fetched 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 appears in the lower field.
4. Click Copy to copy the result to the clipboard.

For more details on how the converter works, supported dialects, and limitations, see the article SQL dialect converter to YQL.

Creating objects

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

• Create Table — create a new table.
• Create Topic — create a new topic.

Plugin update

Automatic updates are only supported when installing via the P2 repository URL. DBeaver remembers the source (repository URL) and when a new version is published, it offers an update in one of two ways:

1. Automatically on the next DBeaver launch (if update checking is 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 → unsigned content warning → restart).

When installing from a ZIP archive, the update is performed manually: download the new archive from the GitHub Releases page, open Help → Installation Information, select the plugin, click Uninstall, then install the new version again.