[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for YDB](../index.md) > [Step-by-step guides](index.md) > Connecting to a database using the YDB CLI

# Connecting to a database using the YDB CLI

The YDB CLI enables you to manage your data in Yandex Managed Service for YDB from the command line. You can use it to operate your databases in systems without a GUI or to automate your tasks using scripts.

First, you need to install the [YDB CLI](https://ydb.tech/docs/en//reference/ydb-cli/install). To connect to your Yandex Managed Service for YDB database from the YDB CLI, specify the [endpoint and path](#endpoint-and-path) and [select and set up](#auth) the authentication mode.

## Configuring security groups {#configuring-security-groups}

To connect to your database in Dedicated mode, allow incoming and outgoing traffic over TCP on port `2135`. Make sure the assigned [security group](../../vpc/concepts/security-groups.md) has the relevant rule, or add one:

* **Port range**: `2135`.
* **Protocol**: `TCP`.
* **Source**: `CIDR`.
* **CIDR blocks**: `0.0.0.0/0`.

## Get connection credentials {#endpoint-and-path}

To get the database connection credentials:

{% list tabs group=instructions %}

- Management console {#console}

  1. Navigate to the [management console](https://console.yandex.cloud) and select a folder containing your database.
  1. Navigate to **Managed Service for YDB**.
  1. Select the database for which you need to get the endpoint and path.
      
      * The database endpoint is specified under **Connection** in the first part of the **Endpoint** field value (preceding `/?database=`):

          >For example, the endpoint for a database in _serverless mode_ is `grpcs://ydb.serverless.yandexcloud.net:2135`, and in _dedicated mode_, is `grpcs://lb.etnk1u65e4shtgj338va.ydb.mdb.yandexcloud.net:2135`.
      * The database path is specified under **Connection** in the second part of the **Endpoint** field value (following `/?database=`).
      
          >Example of a database path: `/ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1`.

- Yandex Cloud CLI {#cli}

  1. If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).
  1. Get the list of databases in the folder:

      ```bash
      yc ydb database list
      ```

      Result:

      ```text
      +----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
      |          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 |
      +----------------------+----------------+-------------+-------------------------------------------------------------------------------------------------------------------------------+---------------------+---------+
      ```

      You can find the database connection credentials 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`

- API {#api}

  Use the [get](../api-ref/Database/get.md) REST API method for the [Database](../api-ref/Database/index.md) resource or the [DatabaseService/Get](../api-ref/grpc/Database/get.md) gRPC API call and provide the database ID in the `databaseId` request parameter.

  You can find the database connection credentials 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`

  You can get the database ID with the [list of databases](manage-databases.md#list-db).

{% endlist %}

## Set up authentication {#auth}

Select the authentication mode:

* [IAM token](../../iam/concepts/authorization/iam-token.md): Recommended for performing one-time operations under a [Yandex Cloud account](../../iam/concepts/users/accounts.md#passport) or a [federated account](../../iam/concepts/users/accounts.md#saml-federation). The maximum lifetime of an IAM token is 12 hours.
* [Authorized access key](../../iam/concepts/authorization/key.md): Recommended for running YDB CLI commands from outside Yandex Cloud under a [service account](../../iam/concepts/index.md#sa).
* [Metadata service](../../compute/operations/vm-connect/auth-inside-vm.md#auth-inside-vm.md): Most secure and efficient mode used for running commands on VMs inside Yandex Cloud. [Yandex Cloud Functions](../../functions/index.md) supports it as well.

Set up the mode you selected:

{% list tabs %}

- IAM token

  1. Use the [Yandex Cloud CLI](../../cli/index.md) to get an IAM token:

      ```bash
      yc iam create-token
      ```

  1. Save the token to a file.
  1. In your YDB CLI commands, provide the path to this file in the `--iam-token-file` parameter.

      To skip this step every time you run a command, save the IAM token value to the `IAM_TOKEN` environment variable or [set up a YDB CLI profile](https://ydb.tech/docs/en//reference/ydb-cli/profile/create).
  1. Check the connection by requesting user information:

      ```bash
      ydb \
        --endpoint <endpoint> \
        --database <name> \
        --iam-token-file <path> \
        discovery whoami
      ```

      * `--endpoint`: Database endpoint.
      * `--database`: Path to the database.
      * `--iam-token-file`: Path to the IAM token file.

      >Command example:
      >
      >```bash
      >ydb \
      >  --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
      >  --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
      >  --iam-token-file iam-token.txt \
      >  discovery whoami
      >```
      >
      >Result:
      >
      >```text
      >User SID: aje6o75au36h********@as
      >```

- Authorized access key

  1. If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).
  1. [Create](../../iam/operations/sa/create.md) a service account to access your database. The service account must be in the same folder as the database and have the `viewer` or `viewer` + `editor` role(s) depending on the database permissions you need.
  1. Use the [Yandex Cloud CLI](../../cli/index.md) to create an authorized key for the service account:

      ```bash
      yc iam key create \
        --service-account-name <name> \
        --output <path>
      ```

      * `--service-account-name`: Service account name.
      * `--output`: Path to the authorized key file.

  1. In your YDB CLI commands, provide the path to this authorized key file in the `--sa-key-file` parameter.

      To skip this step every time you run a command, save the file path to the `SA_KEY_FILE` environment variable or [set up a YDB CLI profile](https://ydb.tech/docs/en//reference/ydb-cli/profile/create).

  1. Check the connection by requesting user information:

      ```bash
      ydb \
        --endpoint <endpoint> \
        --database <name> \
        --sa-key-file <path>\
        discovery whoami
      ```

      * `--endpoint`: Database endpoint.
      * `--database`: Path to the database.
      * `--sa-key-file`: Path to the file with the private key and public key ID.

      Command example:

      >```bash
      >ydb \
      >  --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
      >  --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
      >  --sa-key-file sa-key-file.txt \
      >  discovery whoami
      >```
      >
      >Result:
      >
      >```text
      >User SID: aje6o75au36h********@as
      >```

- Metadata service

  When running a YDB CLI command from a Yandex Cloud VM, provide the `--use-metadata-credentials` parameter. The YDB CLI will get an IAM token via the metadata service.

  To skip this step every time you run a command, set the `USE_METADATA_CREDENTIALS` environment variable to `1` or [set up a YDB CLI profile](https://ydb.tech/docs/en//reference/ydb-cli/profile/create).

  Check the connection by requesting user information:

  ```bash
  ydb \
    --endpoint <endpoint> \
    --database <name> \
    --use-metadata-credentials \
    discovery whoami
  ```

  * `--endpoint`: Database endpoint.
  * `--database`: Path to the database.
  * `--use-metadata-credentials`: Use the metadata service.

  >Command example:
  >
  >```bash
  >ydb \
  >  --endpoint grpcs://ydb.serverless.yandexcloud.net:2135 \
  >  --database /ru-central1/b1gia87mbaomkfvs6rgl/etnudu2n9ri35luqe4h1 \
  >  --use-metadata-credentials \
  >  discovery whoami
  >```
  >
  >Result:
  >
  >```text
  >User SID: aje6o75au36h********@as
  >```

{% endlist %}