---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.4
alternate:
  - https://ydb.tech/docs/en/reference/ydb-cli/connect.md
  - https://ydb.tech/docs/ru/reference/ydb-cli/connect.md
sourcePath: ru/core/reference/ydb-cli/connect.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt


<!-- source: ru/reference/ydb-cli/_includes/connect.md -->
# Соединение CLI с базой данных и аутентификация

<!-- markdownlint-disable blanks-around-fences -->

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

YDB CLI определяет, с какой БД необходимо соединиться и какой [режим аутентификации](https://ydb.tech/docs/ru/security/authentication.md) использовать из следующих источников (в порядке убывания приоритета):

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

Для того чтобы YDB CLI попробовал соединиться с БД, в результате исполнения данных шагов должен быть определен [эндпоинт](https://ydb.tech/docs/ru/concepts/connect.md#endpoint) и [путь базы данных](https://ydb.tech/docs/ru/concepts/connect.md#database).

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

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

## Параметры командной строки {#command-line-pars}

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

``` bash
ydb <опции_соединения> <команда> <опции_команды>
```

- `-e, --endpoint <endpoint>` — [эндпоинт](https://ydb.tech/docs/ru/concepts/connect.md#endpoint) - основной параметр соединения, позволяющий найти сервер YDB в сети. Если порт не указан, применяется 2135. Если протокол не указан, то в публичных сборках YDB CLI применяется gRPCs (с шифрованием).
- `-d, --database <database>` — [путь базы данных](https://ydb.tech/docs/ru/concepts/connect.md#database).
- `--no-discovery` — пропустить этап discovery, на котором запрашивается список адресов для подключения к кластеру YDB. Если эта опция установлена, подключение будет производиться напрямую к эндпоинту, указанному пользователем (с помощью опции `-e`).


<!-- source: ru/reference/ydb-cli/_includes/auth/options.md -->
<!-- markdownlint-disable blanks-around-fences -->

<!-- source: ru/reference/ydb-cli/_includes/auth/options_header.md -->
Режим и параметры аутентификации выбираются заданием одной из перечисленных ниже опций:
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_header.md -->



<!-- source: ru/reference/ydb-cli/_includes/auth/options_cloud.md -->
- `--token-file <filepath>` : используется режим аутентификации **Access Token**, в качестве которого используется содержимое файла, указанное в значении данной опции
- `--yc-token-file <filepath>` : используется режим аутентификации **Refresh Token**, в качестве которого используется содержимое файла, указанное в значении данной опции
- `--use-metadata-credentials` : используется режим аутентификации **Metadata**
- `--sa-key-file <filepath>` : используется режим аутентификации **Service Account Key**, а ключ и другие параметры загружаются из JSON-файла, указанного в значении данной опции
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_cloud.md -->

<!-- source: ru/reference/ydb-cli/_includes/auth/options_static.md -->
- `--user <username>` : используется режим аутентификации по логину и паролю, в качестве логина используется значение данной опции. Дополнительно могут быть указаны:

  - `--password-file <filename>` : пароль читается из контента указанного файла
  - `--no-password` : определяет пустой пароль
  Пароль будет запрошен в интерактивном режиме в случае, если в параметрах командной строки не указана ни одна из опций определения пароля из перечисленных выше.
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_static.md -->

<!-- source: ru/reference/ydb-cli/_includes/auth/options_oauth2.md -->
- `--oauth2-key-file <filepath>` : используется режим аутентификации [**OAuth 2.0 token exchange**](https://www.rfc-editor.org/rfc/rfc8693), а ключ и другие параметры загружаются из [JSON файла](https://ydb.tech/docs/ru/reference/ydb-sdk/auth.md#oauth2-key-file-format), указанного в значении данной опции. Опция `--iam-endpoint` используется для задания endpoint для обмена токена в формате `<schema>://<host>:<port>/<path>` (через параметр YDB CLI, профиль либо переменную окружения).
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_oauth2.md -->

<!-- source: ru/reference/ydb-cli/_includes/auth/options_multiple.md -->
Если в командной строке задано одновременно несколько из перечисленных выше опций, то CLI выдаст ошибку с просьбой указать ровно одну:

```bash
$ ydb --use-metadata-credentials --iam-token-file ~/.ydb/token scheme ls
More than one auth method were provided via options. Choose exactly one of them
Try "--help" option for more info.
```
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_multiple.md -->

<!-- source: ru/reference/ydb-cli/_includes/auth/options_cloud_additional.md -->
При использовании режимов аутентификации, предусматривающих ротацию токена с его периодическим перезапросом в IAM (**Refresh Token**, **Service Account Key**, **OAuth 2.0 token exchange**), может быть установлен специальный параметр, указывающий где размещен сервис IAM:

- `--iam-endpoint <URL>` : Задает URL сервиса IAM для обращения за новыми токенами в режимах аутентификации, подразумевающих ротацию токенов. Значение по умолчанию — `"iam.api.cloud.yandex.net"`.
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options_cloud_additional.md -->
<!-- endsource: ru/reference/ydb-cli/_includes/auth/options.md -->

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

Если в командной строке при вызове YDB CLI не указан какой-либо параметр соединения, то CLI производит попытку его определения по [профилю](https://ydb.tech/docs/ru/reference/ydb-cli/profile/index.md), выбранному опцией командной строки `--profile`.

В профиле может быть определено большинство переменных, аналогичных опциям из раздела [параметры командной строки](#command-line-pars). Обработка их значений производится также как и параметров командной строки.

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

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

<!-- source: ru/reference/ydb-cli/_includes/auth/env.md -->
<!-- source: ru/reference/ydb-cli/_includes/auth/env_cloud.md -->
- Eсли задано значение переменной окружения `IAM_TOKEN`, то используется режим аутентификации **Access Token**, в который передается значение данной переменной
- Иначе, если задано значение переменной окружения `YC_TOKEN`, то используется режим аутентификации **Refresh Token**, а токен для передачи на IAM endpoint при перезапросе берется из значения этой переменной
- Иначе, если задано значение переменной окружения `USE_METADATA_CREDENTIALS`, равное 1, то используется режим аутентификации **Metadata**
- Иначе, если задано значение переменной окружения `SA_KEY_FILE`, то используется режим аутентификации **Service Account Key**, а ключ загружается из файла, имя которого указано в данной переменной
<!-- endsource: ru/reference/ydb-cli/_includes/auth/env_cloud.md -->



<!-- source: ru/reference/ydb-cli/_includes/auth/env_static.md -->
- Если задано значение переменной окружения `YDB_USER` или `YDB_PASSWORD`, то используется режим аутентификации по логину и паролю. Логин считывается из переменной `YDB_USER`; если он не задан, то выдается ошибка `User password was provided without user name`. Пароль считывается из переменной `YDB_PASSWORD`; если она не задана, то в зависимости от наличия опции командной строки `--no-password` применяется либо пустой пароль, либо пароль будет запрошен интерактивно.
<!-- endsource: ru/reference/ydb-cli/_includes/auth/env_static.md -->

<!-- source: ru/reference/ydb-cli/_includes/auth/env_oauth2.md -->
- Иначе, если задано значение переменной окружения `YDB_OAUTH2_KEY_FILE`, то используется режим аутентификации [**OAuth 2.0 token exchange**](https://www.rfc-editor.org/rfc/rfc8693), а параметры для обмена токена загружаются из [JSON файла](https://ydb.tech/docs/ru/reference/ydb-sdk/auth.md#oauth2-key-file-format), имя которого указано в данной переменной. Опция `--iam-endpoint` используется для задания endpoint для обмена токена в формате `<schema>://<host>:<port>/<path>` (через параметр YDB CLI, профиль либо переменную окружения).
<!-- endsource: ru/reference/ydb-cli/_includes/auth/env_oauth2.md -->
<!-- endsource: ru/reference/ydb-cli/_includes/auth/env.md -->

## Параметры из активированного профиля {#activated-profile}

Если на предыдущих шагах не удалось определить какой-либо параметр соединения и в командной строке не был явно указан профиль опцией `--profile`, то YDB CLI пробует использовать параметры соединения из [активированного профиля](https://ydb.tech/docs/ru/reference/ydb-cli/profile/activate.md).

## Сообщения об ошибках {#errors}

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

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить [эндпоинт](https://ydb.tech/docs/ru/concepts/connect.md#endpoint), то выполнение команды будет прервано с выдачей сообщения `Missing required option 'endpoint'`.

Если все шаги из приведенных в начале данной статьи пройдены, но не удалось определить [путь базы данных](https://ydb.tech/docs/ru/concepts/connect.md#database), то выполнение команды будет прервано с выдачей сообщения `Missing required option 'database'`.

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

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

## Дополнительные параметры {#additional}

При использовании протокола gRPCs (с шифрованием) может потребоваться [выбор корневого сертификата](https://ydb.tech/docs/ru/concepts/connect.md#tls-cert):

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

## Проверка аутентификации {#whoami}

Сервисная команда YDB CLI [`discovery whoami`](https://ydb.tech/docs/ru/reference/ydb-cli/commands/discovery-whoami.md) позволяет проверить, под какой учетной записью вы фактически аутентифицировались на сервере.
<!-- endsource: ru/reference/ydb-cli/_includes/connect.md -->