Connecting to a database using the YDB CLI
The YDB CLI is a tool for managing your data in Yandex Managed Service for YDB from the command line. You can use the YDB CLI to perform actions with your database in systems that have no GUI or to automate your tasks using scripts.
Before you start, install the YDB CLI
Configuring security groups
To connect to your DB in Dedicated mode, allow incoming and outgoing traffic over TCP on port 2135
. Make sure the assigned security group contains the appropriate rule, or add one:
- Port range:
2135
- Protocol:
TCP
- Source:
CIDR
- CIDR blocks:
0.0.0.0/0
Get connection details
To get the database connection details:
-
Go to the management console
. -
Select the folder hosting your DB and go to Managed Service for YDB.
-
Select the DB you want to get the endpoint and path for.
-
The DB endpoint is specified under Connection in the first part of the Endpoint field value (preceding
/?database=
):For example, the endpoint for a DB in Serverless mode is
grpcs://ydb.serverless.yandexcloud.net:2135
and in Dedicated mode isgrpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135
. -
The DB path is specified under Connection in the second part of the Endpoint field value (following
/?database=
).Sample DB path:
/ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1
.
-
-
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
-
Get a list of databases in the folder:
yc ydb database list
Result:
+----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+ | 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 | +----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
DB connection details are specified in the
ENDPOINT
column.For example, for a Serverless database:
- Endpoint:
grpcs://ydb.serverless.yandexcloud.net:2135
. - Path:
/ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1
.
For a Dedicated database:
- Endpoint:
grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135
. - Path:
/ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va
.
- Endpoint:
Use the get REST API method for the Database resource or the DatabaseService/Get gRPC API call and provide the database ID in the databaseId
request parameter.
Database connection details are specified in the endpoint
parameter.
For example, for a Serverless database:
- Endpoint:
grpcs://ydb.serverless.yandexcloud.net:2135
.- Path:
/ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1
.For a Dedicated database:
- Endpoint:
grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135
.- Path:
/ru-central1/b1gia87mbaomkfvs6rgl/etnk1u65e4shtgj338va
.
You can get the database ID with a list of databases.
Set up authentication
Select one of the authentication modes:
- OAuth token: Allows you to run commands only on behalf of a Yandex Cloud account. The token is valid for 1 year. This mode is not recommended for production environments.
- IAM token: Recommended for performing one-time operations on behalf of a Yandex Cloud account or a federated account. IAM token's maximum lifetime is 12 hours.
- Authorized access key: Recommended for running YDB CLI commands from outside Yandex Cloud under a service account.
- Metadata service: The most secure and efficient mode. Used for running commands on VMs inside Yandex Cloud. Also supported by Yandex Cloud Functions.
Set up the selected mode:
Get an OAuth token by sending a request--yc-token-file
parameter.
To avoid entering it every time you run commands, save the OAuth token value to the YC_TOKEN
environment variable or set up a YDB CLI profile
Check that the connection is correct by requesting user information:
ydb \
--endpoint <endpoint> \
--database <name> \
--yc-token-file <path> \
discovery whoami
--endpoint
: DB endpoint.--database
: DB path.--yc-token-file
: Path to the OAuth token file.
Command example:
ydb \ --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \ --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \ --yc-token-file oauth-token.txt \ discovery whoami
Result:
User SID: aje6o75au36h********@as
-
Use the Yandex Cloud CLI to get an IAM token:
yc iam create-token
-
Save the token to a file.
-
When running a YDB CLI command, specify the path to the file with your IAM token in the
--iam-token-file
parameter.To avoid entering it every time you run commands, save the IAM token value to the
IAM_TOKEN
environment variable or set up a YDB CLI profile . -
Check that the connection is correct by requesting user information:
ydb \ --endpoint <endpoint> \ --database <name> \ --iam-token-file <path> \ discovery whoami
--endpoint
: DB endpoint.--database
: DB path.--iam-token-file
: Path to the IAM token file.
Command example:
ydb \ --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \ --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \ --iam-token-file iam-token.txt \ discovery whoami
Result:
User SID: aje6o75au36h********@as
-
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
-
Create a service account to access your DB. The service account must be in the same folder as the database and have the
viewer
orviewer
+editor
role depending on what access to the DB is required. -
Use the Yandex Cloud CLI to create an authorized key for the service account:
yc iam key create \ --service-account-name <name> \ --output <path>
--service-account-name
: Name of the service account.--output
: Path to the file with the authorized key.
-
When running a YDB CLI command, specify the path to the file with your service account's authorized access key in the
--sa-key-file
parameter.To avoid entering it every time you run commands, save the file path to the
SA_KEY_FILE
environment variable or set up a YDB CLI profile . -
Check that the connection is correct by requesting user information:
ydb \ --endpoint <endpoint> \ --database <name> \ --sa-key-file <path>\ discovery whoami
--endpoint
: DB endpoint.--database
: DB path.--sa-key-file
: Path to the file with the private key and public key ID.
Command example:
ydb \ --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \ --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \ --sa-key-file sa-key-file.txt \ discovery whoami
Result:
User SID: aje6o75au36h********@as
When running a YDB CLI command from a Yandex Cloud VM, specify the --use-metadata-credentials
parameter. The YDB CLI will get an IAM token via the metadata service.
To avoid entering it every time you run commands, set the USE_METADATA_CREDENTIALS
environment variable to 1
or set up a YDB CLI profile
Check that the connection is correct by requesting user information:
ydb \
--endpoint <endpoint> \
--database <name> \
--use-metadata-credentials \
discovery whoami
--endpoint
: DB endpoint.--database
: DB path.--use-metadata-credentials
: Use the metadata service.
Command example:
ydb \ --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \ --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \ --use-metadata-credentials \ discovery whoami
Result:
User SID: aje6o75au36h********@as