Connecting to a database using the YDB CLI

Written by

Improved by

Updated at February 9, 2026

Configuring security groups
Get connection credentials
Set up authentication

The YDB CLI enables you to manage your data in Yandex Managed Service for YDB from the command line. You can use it to operate your databases in systems without a GUI or to automate your tasks using scripts.

First, you need to install the YDB CLI. To connect to your Yandex Managed Service for YDB database from the YDB CLI, specify the endpoint and path and select and set up the authentication mode.

Configuring security groups

To connect to your database in Dedicated mode, allow incoming and outgoing traffic over TCP on port 2135. Make sure the assigned security group has the relevant rule, or add one:

Port range: 2135.
Protocol: TCP.
Source: CIDR.
CIDR blocks: 0.0.0.0/0.

Get connection credentials

To get the database connection credentials:

Management console

Yandex Cloud CLI

API

Navigate to the management console and select a folder containing your database.
Go to Managed Service for YDB.
Select the database for which you need to get the endpoint and path.
- The database endpoint is specified under Connection in the first part of the Endpoint field value (preceding /?database=):
  
  For example, the endpoint for a database in serverless mode is grpcs://ydb.serverless.yandexcloud.net:2135, and in dedicated mode, is grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135.
- The database path is specified under Connection in the second part of the Endpoint field value (following /?database=).
  
  Example of a database path: /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

Get the list of databases in the folder:

yc ydb database list

Result:

+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
|          ID          |      NAME      | DESCRIPTION |                                                           ENDPOINT                                                            |     CREATED AT      | STATUS  |
+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
| etnudu2n9ri35luqe4h1 | ydb-serverless |             | grpcs://ydb.serverless.yandexcloud.net:2135/?database=/ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1                  | 2022-05-29 21:10:35 | RUNNING |
| etnk1u65e4shtgj338va | ydb-dedicated  |             | grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135/?database=/ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va | 2022-05-31 10:10:12 | RUNNING |
+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+

You can find the database connection credentials in the ENDPOINT column.

For example, for a serverless database:

Endpoint: grpcs://ydb.serverless.yandexcloud.net:2135

Path: /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1

For a dedicated database:

Endpoint: grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135

Path: /ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va

Use the get REST API method for the Database resource or the DatabaseService/Get gRPC API call and provide the database ID in the databaseId request parameter.

You can find the database connection credentials in the endpoint column.

For example, for a serverless database:

Endpoint: grpcs://ydb.serverless.yandexcloud.net:2135

Path: /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1

For a dedicated database:

Endpoint: grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135

Path: /ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va

You can get the database ID with the list of databases.

Set up authentication

Select the authentication mode:

OAuth token: Allows you to run commands only under a Yandex Cloud account. The token is valid for 1 year. This mode is not recommended for production environments.
IAM token: Recommended for performing one-time operations under a Yandex Cloud account or a federated account. The maximum lifetime of an IAM token is 12 hours.
Authorized access key: Recommended for running YDB CLI commands from outside Yandex Cloud under a service account.
Metadata service: Most secure and efficient mode used for running commands on VMs inside Yandex Cloud. Yandex Cloud Functions supports it as well.

Set up the mode you selected:

OAuth token

IAM token

Authorized access key

Metadata service

Get an OAuth token by sending a request and save it to a file. In your YDB CLI commands, provide the path to this file in the --yc-token-file parameter.

To skip this step every time you run a command, save the OAuth token value to the YC_TOKEN environment variable or set up a YDB CLI profile.

Check the connection by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --yc-token-file <path> \
  discovery whoami

--endpoint: Database endpoint.
--database: Path to the database.
--yc-token-file: Path to the OAuth token file.

Here is a command example:

ydb \
 --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
 --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --yc-token-file oauth-token.txt \
 discovery whoami

Result:

User SID: aje6o75au36h********@as

Use the Yandex Cloud CLI to get an IAM token:
```
yc iam create-token
```
Save the token to a file.
In your YDB CLI commands, provide the path to this file in the --iam-token-file parameter.

To skip this step every time you run a command, save the IAM token value to the IAM_TOKEN environment variable or set up a YDB CLI profile.

Check the connection by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --iam-token-file <path> \
  discovery whoami

--endpoint: Database endpoint.
--database: Path to the database.
--iam-token-file: Path to the IAM token file.

Here is a command example:

ydb \
 --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
 --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --iam-token-file iam-token.txt \
 discovery whoami

Result:

User SID: aje6o75au36h********@as

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.
Create a service account to access your database. The service account must be in the same folder as the database and have the viewer or viewer + editor role(s) depending on the database permissions you need.
Use the Yandex Cloud CLI to create an authorized key for the service account:
```
yc iam key create \
  --service-account-name <name> \
  --output <path>
```
- --service-account-name: Service account name.
- --output: Path to the authorized key file.
In your YDB CLI commands, provide the path to this authorized key file in the --sa-key-file parameter.

To skip this step every time you run a command, save the file path to the SA_KEY_FILE environment variable or set up a YDB CLI profile.

Check the connection by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --sa-key-file <path>\
  discovery whoami

--endpoint: Database endpoint.
--database: Path to the database.
--sa-key-file: Path to the file with the private key and public key ID.

Here is a command example:

ydb \
 --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
 --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --sa-key-file sa-key-file.txt \
 discovery whoami

Result:

User SID: aje6o75au36h********@as

When running a YDB CLI command from a Yandex Cloud VM, provide the --use-metadata-credentials parameter. The YDB CLI will get an IAM token via the metadata service.

To skip this step every time you run a command, set the USE_METADATA_CREDENTIALS environment variable to 1 or set up a YDB CLI profile.

Check the connection by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --use-metadata-credentials \
  discovery whoami

--endpoint: Database endpoint.
--database: Path to the database.
--use-metadata-credentials: Use the metadata service.

Here is a command example:

ydb \
 --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
 --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --use-metadata-credentials \
 discovery whoami

Result:

User SID: aje6o75au36h********@as

Connecting to a database using the YDB CLI

Configuring security groupsConfiguring security groups

Get connection credentialsGet connection credentials

Set up authenticationSet up authentication

Was the article helpful?

Configuring security groups

Get connection credentials

Set up authentication