Connecting to YDB using the VS Code plugin

Visual Studio Code is a free, cross-platform, open-source code editor that supports a wide ecosystem of extensions for working with databases, language servers, and development tools.

YDB for VS Code is a VS Code extension with native support for YDB. 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 with syntax highlighting, visualization of execution plans, session and cluster monitoring, access control management (ACL), a built-in MCP server for AI assistants, 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 (row and column), topics, views, external data sources, external tables, transfers, streaming queries.
• System objects: system views (.sys), resource pools.
• YQL editor with syntax highlighting, autocompletion of tables and columns.
• Query execution and result visualization: table, JSON, diagram.
• Visualization of the query execution plan (EXPLAIN).
• Active session monitoring via .sys/query_sessions.
• Cluster dashboard based on YDB Embedded UI: CPU load, memory usage, network traffic (updates every 10 seconds).
• Management of access rights (ACL): viewing permissions on database objects.
• Generation of DDL scripts ( CREATE) for any database object.
• Management of streaming queries: viewing, starting, stopping.
• SQL query converter from other dialects (PostgreSQL, MySQL, ClickHouse, and others) to YQL.
• Built-in MCP server — direct access to databases from AI assistants (Claude Code and others).
• Semantic search in YQL documentation (RAG) for AI-assisted query writing.

Requirements

The plugin requires Visual Studio Code version 1.75.0 or newer.

Installing the plugin

The plugin can be installed from the VS Code Marketplace or from a .vsix file on the GitHub Releases page.

Installation from VS Code Marketplace

1. Open the Extensions panel in VS Code (Ctrl+Shift+X / Cmd+Shift+X).
2. In the search bar, enter YDB for VS Code and select the extension from publisher ydb-tech ( direct link).
3. Click Install.

Alternatively, you can install the plugin from the Marketplace with a single command in the terminal:

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

Installation from a VSIX file

This method is suitable if you need a specific version or do not have access to the Marketplace.

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

2. Install the extension using one of the following methods:

   • Via terminal:

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

     Where X.X.X — the number of the downloaded version.

   • Via VS Code interface:

     1. Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).
     2. Click ... (three dots) in the top-right corner of the panel.
     3. Select Install from VSIX....
     4. Specify the path to the downloaded .vsix file.

After installation by any method, restart VS Code. The YDB icon will appear in the Activity Bar.

Creating a connection to YDB

1. Click the YDB icon in the Activity Bar on the left.

2. In the Connections panel, click the Add Connection button (+ icon).

3. The connection creation form will open. Fill in the fields:

   Field	Description	Example
   Connection Name	Arbitrary connection name	my-ydb
   Host	Endpoint of the endpoint of the YDB cluster	ydb.example.com
   Port	Port (default 2135)	2135
   Database	Path to the database	/Root/database
   Monitoring URL	URL of YDB Embedded UI, used for the dashboard (filled in automatically based on the host, can be overridden)	http://ydb.example.com:8765
   Secure connection (grpcs)	Use a secure connection (grpcs://)	☑
   Use RAG	Enable search in YQL documentation for this connection	☑

4. If necessary, specify the path to a custom CA certificate (PEM) in the CA Certificate File field — for connections with non-standard TLS. If the field is left empty, the built-in Yandex Cloud certificate is used.

5. Select the authentication method from the Auth type drop-down list (see Authentication methods).

6. Click Test Connection to verify the settings. If the connection is successful, a success message will appear.

7. Click Save. The connection will appear in the Connections panel.

Authentication methods

The plugin supports all authentication methods available in YDB. The method is selected in the Auth type dropdown on the connection creation form.

Anonymous

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

Static Credentials (login and password)

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

Access 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 Key File

Authentication by a service account key of Yandex Cloud. Specify the path to the JSON file with the key in the Service Account Key File field (use the Browse button to select the file). For more details 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 Service

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

Object navigator

After connecting, click the connection in the Connections panel — the Navigator panel opens with a hierarchy of YDB objects. The navigator contains the following sections:

• Tables — tables (row and column), organized by subdirectories according to the path in YDB.
• System Views — system views (.sys), such as query_sessions, partition_stats.
• Views — views.
• Topics — topics.
• External Data Sources — external data sources.
• External Tables — external tables.
• Resource Pools — resource pools.
• Transfers — data transfers.
• Streaming Queries — streaming queries.

Right-clicking any object in the navigator opens a context menu with available actions.

Working with the plugin

Query workspace

Open the query workspace via Ctrl+Shift+Q (Cmd+Shift+Q on macOS) or click Open Query Workspace in the connection context menu. In the workspace, you can write and execute YQL queries, view history and results.

To quickly open the editor with a pre-filled query, right-click a table or view in the navigator and select:

• Show Preview — SELECT of the first 100 rows.
• Make Query — SELECT with the object name.

YQL editor

The editor supports:

• Syntax highlighting for YQL: keywords, data types, built-in functions.
• Auto-completion of table and column names (based on the schema of the connected database).
• Query execution: Ctrl+Enter (Cmd+Enter on macOS).

Example YQL query:

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

Execution results are displayed in the Results panel as a table, JSON, or diagram (switch via tabs).

EXPLAIN and execution plan

Select Explain YQL Query in the editor context menu or in the command palette (Ctrl+Shift+P) to get the query execution plan. The plugin displays the plan's operation tree in text form.

Session manager

The Sessions panel (Activity Bar → YDB) displays all active sessions with the current query, state, and duration (data from the system view .sys/query_sessions). The Toggle Hide Idle button hides sessions without an active query.

Cluster dashboard

The Database Load panel (Activity Bar → YDB) displays real-time cluster load (updated every 10 seconds):

• CPU load (% and number of cores).
• Memory usage (% and amount).
• Network traffic.

Streaming queries

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

• View the source YQL (View Source).
• Start and stop (Start / Stop).

SQL dialect converter

The plugin allows converting an SQL query written in another dialect (PostgreSQL, MySQL, ClickHouse, and others) to YQL. The converter is available in the Convert Dialect panel on the Activity Bar.

To convert a query:

1. In the Source Dialect dropdown, select the source SQL dialect.
2. Paste the source SQL code into the Input SQL field.
3. Click Convert. The result appears in the lower field.
4. Copy the result to use in the YQL editor.

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

View permissions

Right-click an object in the navigator and select View Permissions to view the access rights (ACL) assigned to this object.

DDL generation

Right-click a table, topic, or other object in the navigator and select Create DDL to get the CREATE script of the object.

Creating objects

Right-click the appropriate folder in the navigator to create a new object:

• New Row Table / New Column Table — create a row or column table.
• New Topic — create a topic.
• New View — create a view.
• New Object Storage Data Source / New YDB Data Source — create an external data source.
• New CSV/JSON/Parquet External Table — create an external table.
• New Transfer — create a transfer.
• New Streaming Query — create a streaming query.

Integration with AI assistants (MCP)

The plugin runs a built-in MCP server (Model Context Protocol), which allows AI assistants (Claude Code and others) to directly execute queries against YDB databases configured in the plugin.

Port configuration

The server runs on port 3333 (localhost only) by default. You can change the port in VS Code settings:

{
  "ydb.mcpPort": 3333
}

If the port is already in use, the extension will show a warning and continue working without MCP.

Connecting Claude Code

1. Make sure the YDB extension is running in VS Code and at least one connection is added in the Connections panel (see Creating a connection).

2. Register the MCP server in Claude Code globally for the current user:

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

   The --scope user flag saves the configuration globally — the server will be accessible from any directory where Claude Code is launched. Without this flag, the scope local (default) is used, and registration will have to be repeated for each project.

3. Check the connection:

   claude mcp list
   

Available MCP tools

The connection parameter is the connection name as it appears in the Connections panel.

Search YQL documentation (RAG)

The plugin supports semantic and keyword search over YQL documentation using a built-in RAG index (Retrieval-Augmented Generation). This allows AI assistants (via the ydb_yql_help tool) to find relevant fragments of the syntax reference when writing queries.

Enabling RAG

1. When creating or editing a connection, set the Use RAG flag.
2. The plugin will automatically detect the YDB version and download the corresponding index from the cloud on first connection.

Search modes

• Keyword search — works without additional dependencies, used by default.
• Semantic search (vector) — requires a locally running Ollama with the nomic-embed-text embedding model. See Installing Ollama and the embedding model.

The RAG status (Running / Not running) and Ollama status are displayed directly in the connection form.

Installing Ollama and the embedding model

Ollama is a local server for running language models and embedding models. The plugin communicates with it over HTTP to convert documentation texts and search queries into vectors for semantic search.

1. Install Ollama following the instructions on the official download page (macOS, Windows, and Linux are supported).

2. Make sure the Ollama service is running and accessible at http://localhost:11434:

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

   A JSON response with a list of models means the service is running.

3. Download the nomic-embed-text embedding model (~270 MB):

   ollama pull nomic-embed-text
   

4. Make sure the model is available:

   ollama list
   

   The output should contain the line nomic-embed-text.

5. Open the connection form in the plugin and make sure the Ollama status is displayed as Running. If the status is Not running, check that the Ollama service is running and accessible at http://localhost:11434.

Plugin update

The update method depends on how the plugin was installed.

Updating from VS Code Marketplace

If the plugin is installed from the Marketplace, VS Code updates it automatically.

To update the plugin manually:

1. Open the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X).
2. In the search bar, enter YDB for VS Code and open the installed extension.
3. If a new version is available, the Update button will appear — click it.

Updating from a VSIX file

If the plugin is installed from a VSIX file, automatic updates are not available — VS Code does not track updates for manually installed extensions.

1. Download the new .vsix file from the GitHub Releases page.
2. Install it over the old version using the same method as the initial installation — VS Code will automatically replace the previous version.