Подключение к БД с помощью YDB CLI
YDB CLI — инструмент для управления вашими данными в Yandex Managed Service for YDB из командной строки. Вы можете использовать YDB CLI для выполнения действий с БД на системах без графического интерфейса или для автоматизации задач с помощью скриптов.
Перед началом работы установите YDB CLI
Настройка групп безопасности
Для подключения к БД в Dedicated-режиме нужно разрешить входящий и исходящий трафик по протоколу TCP на порте 2135
. Убедитесь, что в назначенной группе безопасности есть соответствующее правило, или добавьте его:
- Диапазон портов —
2135
. - Протокол —
TCP
. - Источник —
CIDR
. - CIDR блоки —
0.0.0.0/0
.
Получите реквизиты для подключения
Чтобы получить реквизиты для подключения к БД:
-
Перейдите в консоль управления
. -
Выберите каталог с вашей БД и перейдите в сервис 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, установите и инициализируйте его.
-
Получите список баз в каталоге:
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-токен с помощью запроса--yc-token-file
укажите путь к файлу с вашим OAuth-токеном.
Чтобы не указывать этот параметр при каждом вызове команды, сохраните значение OAuth-токена в переменную окружения YC_TOKEN
или настройте профиль
Проверьте корректность подключения, запросив информацию о пользователе:
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
-
С помощью 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/b1gia87mbaom********/etnudu2n9ri3******** \ --iam-token-file iam-token.txt \ discovery whoami
Результат:
User SID: aje6o75au36h********@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/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 \
--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