Подключение к БД с помощью YDB CLI

Статья создана

Улучшена

Обновлена 21 апреля 2025 г.

Настройка групп безопасности
Получите реквизиты для подключения
Настройте аутентификацию

YDB CLI — инструмент для управления вашими данными в Yandex Managed Service for YDB из командной строки. Вы можете использовать YDB CLI для выполнения действий с БД на системах без графического интерфейса или для автоматизации задач с помощью скриптов.

Перед началом работы установите YDB CLI. Для подключения к БД Yandex Managed Service for YDB из YDB CLI необходимо указать эндпоинт и путь, а также выбрать и настроить режим аутентификации.

Настройка групп безопасности

Для подключения к БД в Dedicated-режиме нужно разрешить входящий и исходящий трафик по протоколу TCP на порте 2135. Убедитесь, что в назначенной группе безопасности есть соответствующее правило, или добавьте его:

Диапазон портов — 2135.
Протокол — TCP.
Источник — CIDR.
CIDR блоки — 0.0.0.0/0.

Получите реквизиты для подключения

Чтобы получить реквизиты для подключения к БД:

Консоль управления

Yandex Cloud CLI

API

Перейдите в консоль управления.
Выберите каталог с вашей БД и перейдите в сервис Managed Service for YDB.
Выберите базу данных, для которой нужно получить эндпоинт и путь.
- Эндпоинт БД указан в блоке Соединение в первой части значения поля Эндпоинт (часть до вхождения /?database=):
  
  Например, эндпоинт для БД в режиме Serverless — grpcs://ydb.serverless.yandexcloud.net:2135, для БД в режиме Dedicated — grpcs://lb.etnk1u65e4sh********.ydb.mdb.yandexcloud.net:2135.
- Путь БД указан в блоке Соединение во второй части значения поля Эндпоинт (часть после вхождения /?database=).
  
  Пример пути БД: /ru-central1/b1gia87mbaom********/etnudu2n9ri3********.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

Получите список баз в каталоге:

yc ydb database list

Результат:

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

Реквизиты для подключения к БД указаны в колонке ENDPOINT.

Например, для БД в режиме Serverless:

эндпоинт — grpcs://ydb.serverless.yandexcloud.net:2135;

путь — /ru-central1/b1gia87mbaom********/etnudu2n9ri3********.

Для БД в режиме Dedicated:

эндпоинт — grpcs://lb.etnk1u65e4sh********.ydb.mdb.yandexcloud.net:2135;

путь — /ru-central1/b1gia87mbaom********/etnk1u65e4sh********.

Воспользуйтесь методом REST API get для ресурса Database или вызовом gRPC API DatabaseService/Get и передайте в запросе идентификатор требуемой БД в параметре databaseId.

Реквизиты для подключения к БД указаны в параметре endpoint.

Например, для БД в режиме Serverless:

эндпоинт — grpcs://ydb.serverless.yandexcloud.net:2135;

путь — /ru-central1/b1gia87mbaom********/etnudu2n9ri3********.

Для БД в режиме Dedicated:

эндпоинт — grpcs://lb.etnk1u65e4sh********.ydb.mdb.yandexcloud.net:2135;

путь — /ru-central1/b1gia87mbaom********/etnk1u65e4sh********.

Идентификатор БД можно получить со списком БД.

Настройте аутентификацию

Выберите один из режимов аутентификации:

OAuth-токен — позволяет выполнять команды только от имени аккаунта в Yandex Cloud. Время жизни токена 1 год. Режим не рекомендуется для продуктовых сред.
IAM-токен — рекомендуется для выполнения разовых операций от имени аккаунта в Yandex Cloud или федеративного аккаунта. Время жизни токена не более 12 часов.
Авторизованный ключ доступа — рекомендуется для выполнения команд YDB CLI снаружи Yandex Cloud от имени сервисного аккаунта.
Сервис метаданных — наиболее безопасный и производительный режим. Применяется при выполнении команд на виртуальных машинах внутри Yandex Cloud. Также поддерживается сервисом Yandex Cloud Functions.

Настройте выбранный режим:

OAuth-токен

IAM-токен

Авторизованный ключ доступа

Сервис метаданных

Получите OAuth-токен с помощью запроса и сохраните его в файл. При запуске команды YDB CLI в параметре --yc-token-file укажите путь к файлу с вашим OAuth-токеном.

Чтобы не указывать этот параметр при каждом вызове команды, сохраните значение OAuth-токена в переменную окружения YC_TOKEN или настройте профиль YDB CLI.

Проверьте корректность подключения, запросив информацию о пользователе:

ydb \
  --endpoint <эндпоинт> \
  --database <имя> \
  --yc-token-file <путь> \
  discovery whoami

--endpoint — эндпоинт БД.
--database — путь к БД.
--yc-token-file — путь к файлу с OAuth-токеном.

Пример команды:

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

Результат:

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

С помощью Yandex Cloud CLI получите IAM-токен:
```
yc iam create-token
```
Сохраните полученный токен в файл.
При запуске команды YDB CLI в параметре --iam-token-file укажите путь к файлу с вашим IAM-токеном.

Чтобы не указывать этот параметр при каждом вызове команды, сохраните значение IAM-токена в переменную окружения IAM_TOKEN или настройте профиль YDB CLI.

Проверьте корректность подключения, запросив информацию о пользователе:

ydb \
  --endpoint <эндпоинт> \
  --database <имя> \
  --iam-token-file <путь> \
  discovery whoami

--endpoint — эндпоинт БД.
--database — путь к БД.
--iam-token-file — путь к файлу с IAM-токеном.

Пример команды:

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

Результат:

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

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.
Создайте сервисный аккаунт для доступа к БД. Сервисный аккаунт должен располагаться в том же каталоге, что и БД и иметь роль viewer или viewer + editor в зависимости от того, какой доступ к БД необходим.
С помощью Yandex Cloud CLI создайте авторизованный ключ для сервисного аккаунта:
```
yc iam key create \
  --service-account-name <имя> \
  --output <путь>
```
- --service-account-name — имя сервисного аккаунта.
- --output — путь к файлу с авторизованным ключом.
При запуске команды YDB CLI в параметре --sa-key-file укажите путь к файлу с авторизованным ключом доступа сервисного аккаунта.

Чтобы не указывать этот параметр при каждом вызове команды, сохраните путь к файлу в переменную окружения SA_KEY_FILE или настройте профиль YDB CLI.
Проверьте корректность подключения, запросив информацию о пользователе:
```
ydb \
  --endpoint <эндпоинт> \
  --database <имя> \
  --sa-key-file <путь>\
  discovery whoami
```
- --endpoint — эндпоинт БД.
- --database — путь к БД.
- --sa-key-file — путь к файлу с закрытым ключом и идентификатором открытого ключа.
Пример команды:
```
ydb \
 --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
 --database /ru-central1/b1gia87mbaom********/etnudu2n9ri3******** \
 --sa-key-file sa-key-file.txt \
 discovery whoami
```
Результата:
```
User SID: aje6o75au36h********@as
```

При запуске команды YDB CLI из виртуальной машины в Yandex Cloud укажите параметр --use-metadata-credentials. YDB CLI получит IAM-токен с помощью сервиса метаданных.

Чтобы не указывать этот параметр при каждом вызове команды, установите значение переменной окружения USE_METADATA_CREDENTIALS в 1 или настройте профиль YDB CLI.

Проверьте корректность подключения, запросив информацию о пользователе:

ydb \
  --endpoint <эндпоинт> \
  --database <имя> \
  --use-metadata-credentials \
  discovery whoami

--endpoint — эндпоинт БД.
--database — путь к БД.
--use-metadata-credentials — использовать сервис метаданных.

Пример команды:

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

Результат:

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

Подключение к БД с помощью YDB CLI

Настройка групп безопасностиНастройка групп безопасности

Получите реквизиты для подключенияПолучите реквизиты для подключения

Настройте аутентификациюНастройте аутентификацию

Была ли статья полезна?

Настройка групп безопасности

Получите реквизиты для подключения

Настройте аутентификацию