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

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

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

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

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

Важно

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

Группы безопасности находятся на стадии Preview. Если они недоступны в вашей сети, для ресурсов будет разрешен весь входящий и исходящий трафик. Дополнительной настройки не требуется.

Чтобы включить группы безопасности, запросите в технической поддержке доступ к этой функции.

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

Получить реквизиты для подключения к БД можно в консоли управления Yandex Cloud или с помощью интерфейса командной строки Yandex Cloud.

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

YC CLI

Перейдите в консоль управления.
Выберите каталог с вашей БД и перейдите в сервис Yandex Managed Service for YDB.
Выберите базу данных, для которой нужно получить эндпоинт и путь.
- Эндпоинт БД указан в блоке Соединение в строке Эндпоинт:
  
  Например, эндпоинт для БД в режиме Serverless — grpcs://ydb.serverless.yandexcloud.net:2135, для БД в режиме Dedicated — grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135.
- Путь БД указан блоке Соединение в строке Размещение базы данных.
  
  Пример пути БД: /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1.

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

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

yc ydb database list

Результат:

+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
|          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 |
+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+

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

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

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

путь — /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1.

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

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

путь — /ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va.

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

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

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/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --yc-token-file oauth-token.txt \
 discovery whoami

Результат:

User SID: aje6o75au36h5d0yuv2g@as

С помощью CLI Yandex Cloud получите 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/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --iam-token-file iam-token.txt \
 discovery whoami

Результат:

User SID: aje6o75au36h5d0yuv2g@as

Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
Создайте сервисный аккаунт для доступа к БД. Сервисный аккаунт должен располагаться в том же каталоге, что и БД и иметь роль viewer или viewer + editor в зависимости от того, какой доступ к БД необходим.
С помощью CLI Yandex Cloud создайте авторизованный ключ для сервисного аккаунта:
```
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/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --sa-key-file sa-key-file.txt \
 discovery whoami
```
Результата:
```
User SID: aje6o75au36h5d0yuv2g@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/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
 --use-metadata-credentials \
 discovery whoami

Результат:

User SID: aje6o75au36h5d0yuv2g@as

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

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

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

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