Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Connecting to a database using the YDB CLI

Written by
Improved by
Updated at February 18, 2025

The YDB CLI is a tool for managing your data in Yandex Managed Service for YDB from the command line. You can use the YDB CLI to perform actions with your database in systems that have no GUI or to automate your tasks using scripts.

Before you start, 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 authentication mode.

Configuring security groups

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

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

Get connection details

To get the database connection details:

  1. Go to the management console.

  2. Select the folder hosting your DB and go to Managed Service for YDB.

  3. Select the DB you want to get the endpoint and path for.

    • The DB endpoint is specified under Connection in the first part of the Endpoint field value (preceding /?database=):

      For example, the endpoint for a DB in Serverless mode is grpcs://ydb.serverless.yandexcloud.net:2135 and in Dedicated mode is grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135.

    • The DB path is specified under Connection in the second part of the Endpoint field value (following /?database=).

      Example of a DB path: /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1.

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

  2. Get a 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 |
+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+

    DB connection details are specified 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.

Database connection details are specified in the endpoint parameter.

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 a list of databases.

Set up authentication

Select one of the authentication modes:

Set up the selected mode:

Get an OAuth token by sending a request and save it to a file. When running a YDB CLI command, specify the path to the file with your OAuth token in the --yc-token-file parameter.

To avoid entering this parameter 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 that the connection is correct by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --yc-token-file <path> \
  discovery whoami
  • --endpoint: DB endpoint.
  • --database: Path to the DB.
  • --yc-token-file: Path to the OAuth token file.

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

  1. Use the Yandex Cloud CLI to get an IAM token:

    yc iam create-token

  2. Save the token to a file.

  3. When running a YDB CLI command, specify the path to the file with your IAM token in the --iam-token-file parameter.

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

  4. Check that the connection is correct by requesting user information:

    ydb \
  --endpoint <endpoint> \
  --database <name> \
  --iam-token-file <path> \
  discovery whoami
    • --endpoint: DB endpoint.
    • --database: Path to the DB.
    • --iam-token-file: Path to the IAM token file.

    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

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

  2. Create a service account to access your DB. The service account must be in the same folder as the database and have the viewer or viewer + editor role(s) depending on what access to the DB is required.

  3. 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 authorized key file.

  4. When running a YDB CLI command, specify the path to the file with your service account's authorized access key in the --sa-key-file parameter.

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

  5. Check that the connection is correct by requesting user information:

    ydb \
  --endpoint <endpoint> \
  --database <name> \
  --sa-key-file <path>\
  discovery whoami
    • --endpoint: DB endpoint.
    • --database: Path to the DB.
    • --sa-key-file: Path to the file with the private key and public key ID.

    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, specify the --use-metadata-credentials parameter. The YDB CLI will get an IAM token via the metadata service.

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

Check that the connection is correct by requesting user information:

ydb \
  --endpoint <endpoint> \
  --database <name> \
  --use-metadata-credentials \
  discovery whoami
  • --endpoint: DB endpoint.
  • --database: Path to the DB.
  • --use-metadata-credentials: Use the metadata service.

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
Previous
Overview
Next
Managing databases