Connecting the CLI to and authenticating with a database

Connecting the CLI to and authenticating with a database

Command line parameters
Parameters from the profile set by the command-line option
Parameters from environment variables
Parameters from the activated profile
Error messages
- Errors before attempting to establish a DB connection
Additional parameters
Verifying authentication

Most of the YDB CLI commands relate to operations on a YDB database and require establishing a connection to it to be executed.

The YDB CLI determines what DB to connect to and what authentication mode to use based on information from the following sources (in order of priority):

The command line.
The profile set in the --profile command-line option.
Environment variables.
The activated profile.

For the YDB CLI to try connecting to the DB after you completed these steps, make sure to specify the Endpoint and Database location.

If all the steps are completed, but the YDB CLI did not determine the authentication mode, requests will be sent to the YDB server without adding authentication data. This may let you successfully work with locally deployed YDB clusters that require no authentication. For all databases available over the network, such requests will be rejected by the server with an authentication error returned.

For possible situations when the YDB CLI will not try to connect to a database, see the Error messages section below.

Command line parameters

DB connection options in the command line are specified before defining the command and its parameters:

ydb <connection_options> <command> <command_options>

-e, --endpoint <endpoint> : Endpoint: The main connection parameter that allows finding the YDB server on the network. If no port is specified, port 2135 is used. If no protocol is specified, gRPCs (with encryption) is used in YDB CLI public builds.
-d, --database <database> : DB location.

The authentication mode and parameters are selected by setting one of the following options:

--iam-token-file <filepath> : The Access Token authentication mode is used based on the contents of the file specified in this option value.
--yc-token-file <filepath> : The Refresh Token authentication mode is used based on the contents of the file specified in this option value.
--use-metadata-credentials : The Metadata authentication mode is used.
--sa-key-file <filepath> : The Service Account Key authentication mode is used with the key and other parameters taken from the JSON file specified in this option value.
--user <username> : The username and password based authentication mode is used with the username set in this option value. Additionally , you can specify:
- --password-file <filename> : The password is read from the specified file.
- --no-password : Defines an empty password. The password will be requested interactively if none of the password identification options listed above are specified in the command line parameters.

If several of the above options are set simultaneously in the command line, the CLI returns an error asking you to specify only one:

$ 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.

When using authentication modes that involve token rotation along with regularly re-requesting them from IAM (Refresh Token and Service Account Key), a special parameter can be set to indicate where the IAM service is located:

--iam-endpoint <URL> : Sets the URL of the IAM service to request new tokens in authentication modes with token rotation. The default value is "iam.api.cloud.yandex.net".

Parameters from the profile set by the command-line option

If a certain connection parameter is not specified in the command line when calling the YDB CLI, it tries to determine it by the profile set in the --profile command-line option.

The profile may define most variables similar to the options from the Command line parameters section. Their values are processed in the same way as command line parameters.

Parameters from environment variables

If you did not explicitly specify a profile or authentication parameters at the command line, the YDB CLI attempts to determine the authentication mode and parameters from the YDB CLI environment as follows:

If the value of the IAM_TOKEN environment variable is set, the Access Token authentication mode is used, where this variable value is passed.
Otherwise, if the value of the YC_TOKEN environment variable is set, the Refresh Token authentication mode is used and the token to transfer to the IAM endpoint is taken from this variable value when repeating the request.
Otherwise, if the value of the USE_METADATA_CREDENTIALS environment variable is set to 1, the Metadata authentication mode is used.
Otherwise, if the value of the SA_KEY_FILE environment variable is set, the Service Account Key authentication mode is used and the key is taken from the file whose name is specified in this variable.
If the value of the YDB_USER or YDB_PASSWORD environment variable is set, the username and password based authentication mode is used. The username is read from the YDB_USER variable. If it is not set, an error saying User password was provided without user name is returned. The password is read from the YDB_PASSWORD variable. If it is not set, then, depending on whether the --no-password command-line option is specified, either an empty password is used or a password is requested interactively.

Parameters from the activated profile

If some connection parameter could not be determined in the previous steps, and you did not explicitly specify a profile at the command line with the --profile option, the YDB CLI attempts to use the connection parameters from the activated profile.

Error messages

Errors before attempting to establish a DB connection

If all the steps described in the beginning of this article are completed, but the Endpoint is not determined, the command is aborted and an error message saying Missing required option 'endpoint' is returned.

If all the steps described in the beginning of this article are completed, but the DB location is not identified, the command is aborted and an error message saying Missing required option 'database' is returned.

If the authentication mode is known, but the necessary additional parameters are not, the command is aborted and an error message describing the issue is returned:

(No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028): Couldn’t open and read the <filepath> file specified in one of the parameters with the file name and path.