Соединение CLI с базой данных и аутентификация

Большинство команд YDB CLI относится к операциям над базой данных YDB и требует соединения с ней для исполнения.

YDB CLI определяет, с какой БД необходимо соединиться и какой режим аутентификации использовать из следующих источников (в порядке убывания приоритета):

  1. Командной строки
  2. Профиля, выбранного опцией командной строки --profile
  3. Переменных окружения
  4. Активированного профиля

Для того чтобы YDB CLI попробовал соединиться с БД, в результате исполнения данных шагов должен быть определен эндпоинт и путь базы данных.

Если все шаги пройдены, но YDB CLI не определил режим аутентификации, то запросы будут отправляться на сервер YDB без добавления аутентификационных данных. Это может позволить успешно работать с локально развернутыми кластерами YDB, не требующими аутентификации. Для всех доступных по сети баз данных такие запросы будут отклонены сервером с выдачей ошибки аутентификации.

О возможных ситуациях, когда YDB CLI не будет пытаться соединиться с БД, читайте ниже в секции Сообщения об ошибках.

Параметры командной строки

Опции соединения c БД в командной строке указываются перед определением команды и её параметров:

ydb <опции_соединения> <команда> <опции_команды>
  • -e, --endpoint <endpoint>эндпоинт - основной параметр соединения, позволяющий найти сервер YDB в сети. Если порт не указан, применяется 2135. Если протокол не указан, то в публичных сборках YDB CLI применяется gRPCs (с шифрованием).
  • -d, --database <database>путь базы данных.

OpenSource сборка YDB CLI поддерживает только один режим аутентификации -- по логину и паролю:

  • --user <username> : используется режим аутентификации по логину и паролю, в качестве логина используется значение данной опции. Дополнительно могут быть указаны:
    • --password-file <filename> : пароль читается из контента указанного файла
    • --no-password : определяет пустой пароль
      Пароль будет запрошен в интерактивном режиме в случае, если в параметрах командной строки не указана ни одна из опций определения пароля из перечисленных выше.

Параметры из профиля, выбранного опцией командной строки

Если в командной строке при вызове YDB CLI не указан какой-либо параметр соединения, то CLI производит попытку его определения по профилю, выбранному опцией командной строки --profile.

В профиле может быть определено большинство переменных, аналогичных опциям из раздела параметры командной строки. Обработка их значений производится также как и параметров командной строки.

Параметры из переменных окружения

Если в командной строке не был явно указан профиль или в нём не заданы отвечающие за аутентификацию параметры, то YDB CLI пытается определить режим и параметры аутентификации по окружению YDB CLI по следующему алгоритму:

  • Если задано значение переменной окружения YDB_USER или YDB_PASSWORD, то используется режим аутентификации по логину и паролю. Логин считывается из переменной YDB_USER; если он не задан, то выдается ошибка User password was provided without user name. Пароль считывается из переменной YDB_PASSWORD; если она не задана, то в зависимости от наличия опции командной строки --no-password применяется либо пустой пароль, либо пароль будет запрошен интерактивно.

Параметры из активированного профиля

Если на предыдущих шагах не удалось определить какой-либо параметр соединения и в командной строке не был явно указан профиль опцией --profile, то YDB CLI пробует использовать параметры соединения из активированного профиля.

Сообщения об ошибках

Ошибки до попытки установки соединения с БД

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить эндпоинт, то выполнение команды будет прервано с выдачей сообщения Missing required option 'endpoint'.

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить путь базы данных, то выполнение команды будет прервано с выдачей сообщения Missing required option 'database'.

Если режим аутентификации определить удалось, но не удалось определить необходимые дополнительные параметры, то выполнение команды будет прервано с выдачей сообщения, описывающего проблему:

  • (No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028) -- не удалось открыть на чтение файл <filepath>, указанный в одном из параметров, где передается имя файла с путем

Дополнительные параметры

При использовании протокола gRPCs (с шифрованием) может потребоваться выбор корневого сертификата:

  • --ca-file <filepath> : Файл корневого PEM-сертификата для TLS-соединения

В настоящее время корневой сертификат не сохраняется в профиле, и может быть определен только опцией командной строки.

Проверка аутентификации

Сервисная команда YDB CLI discovery whoami позволяет проверить, под какой учетной записью вы фактически аутентифицировались на сервере.