Connecting to a database

To connect to the YDB database from the YDB CLI or an application using the YDB SDK, you’ll need to provide the following data:

  1. Endpoint.
  2. Authentication information.
  3. Database location.

Endpoint

An endpoint is a string structured as protocol://host:port and provided by a YDB cluster owner for proper routing of client queries to its databases over the network infrastructure as well as for network connection initialization. Cloud databases display the endpoint in the management console on the required DB page and also normally provide it via the cloud CLI. In corporate environments, endpoint names YDB are provided by the administration team or obtained in the internal cloud management console.

Examples:

  • grpc://localhost:7135 is an unencrypted data transfer protocol (gRPC) with the server running on port 7135 of the same host as the client.
  • grpcs://ydb.somecorp-int.ru is an encrypted data transfer protocol (gRPCs) with the server running on a host called ydb.somecorp-int.ru on the SomeCorp isolated corporate network and listening for connections on YDB default port 2135.
  • grpcs://ydb.serverless.yandexcloud.net:2135 is an encrypted data transfer protocol (gRPCs), public Yandex.Cloud Serverless YDB server at ydb.serverless.yandexcloud.net, port 2135.

Authentication information

Once a network connection is established, the server starts to accept client requests for processing supplied with authentication information. The server uses it to identify the client’s account and to verify access to execute the query.

The primary operation model assumes that there is a separate system for managing credentials and permissions: IAM (Identity and Access Management). IAM issues a token linked to the account, which the YDB client passes to the server along with a request. The YDB server accesses IAM to verify the token and permissions to perform the requested operation and caches the result.

YDB also supports username and password based authentication without interacting with IAM, but using this model in practice is limited to simple configurations, primarily local ones.

Authentication modes

YDB clients (CLI or SDK) support the following token selection modes to pass tokens in requests:

  • Anonymous: Empty token passed in a request.
  • Access Token: Fixed token set as a parameter for the client (SDK or CLI) and passed in requests.
  • Refresh Token: OAuth token of a user’s personal account set as a parameter for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
  • Service Account Key: Service account attributes and a signature key set as parameters for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests.
  • Metadata: Client (SDK or CLI) periodically accesses a local service to rotate a token (obtain a new one) to pass in requests.

Any owner of a valid token can get access to perform operations; therefore, the principal objective of the security system is to ensure that a token remains private and to protect it from being compromised.

Authentication modes with token rotation, such as Refresh Token and Service Account Key, provide a higher level of security compared to the Access Token mode that uses a fixed token, since only secrets with a short validity period are transmitted to the YDB server over the network.

The highest level of security and performance is provided when using the Metadata mode, since it eliminates the need to work with secrets when deploying an application and allows accessing the IAM system and caching a token in advance, before running the application.

When choosing the authentication mode among those supported by the server and environment, follow the recommendations below:

  • You would normally use Anonymous on self-deployed local YDB clusters that are inaccessible over the network.
  • You would use Access Token when other modes are not supported on server side or for setup/debugging purposes. It does not require that the client access IAM. However, if the IAM system supports an API for token rotation, fixed tokens issued by this IAM usually have a short validity period, which makes it necessary to update them manually in the IAM system on a regular basis.
  • Refresh Token can be used when performing one-time manual operations under a personal account, for example, related to DB data maintenance, performing ad-hoc operations in the CLI, or running applications from a workstation. You can manually obtain this token from IAM once to have it last a long time and save it in an environment variable on a personal workstation to use automatically and with no additional authentication parameters on CLI launch.
  • Service Account Key is mainly used for applications designed to run in environments where the Metadata mode is supported, when testing them outside these environments (for example, on a workstation). It can also be used for applications outside these environments, working as an analog of Refresh Token for service accounts. Unlike a personal account, service account access objects and roles can be restricted.
  • Metadata is used when deploying applications in clouds. Currently, this mode is supported on virtual machines and in Cloud Functions Yandex.Cloud.

The token to specify in request parameters can be obtained in the IAM system that the specific YDB deployment is associated with. In particular, YDB in Yandex.Cloud uses Yandex.Passport OAuth and Yandex.Cloud service accounts. When using YDB in a corporate context, a company’s standard centralized authentication system may be used.

When using modes in which the YDB client accesses the IAM system, the IAM URL that provides an API for issuing tokens can be set additionally. By default, existing SDKs and CLIs attempt to access the Yandex.Cloud IAM API hosted at iam.api.cloud.yandex.net:443.

Database location

Database location (database) is a string that defines where the queried database is located in the YDB cluster. It has the path to file) format and uses the / character as separator. It always starts with a /.

A YDB cluster may have multiple databases deployed, and their location is defined by the cluster configuration. Like the endpoint, database for cloud databases is displayed in the management console on the desired database page, and can also be obtained via the CLI of the cloud provider.

For cloud solutions, databases are created and hosted on the YDB cluster in self-service mode, with no need in involvement of the cluster owner or administrators.

Warning

Applications should not in any way interpret the number and value of database directories, since they are set in the YDB cluster configuration. When using YDB in Yandex.Cloud, database has the format region_name/cloud_id/database_id; however, this format may change going forward for new DBs.

Examples:

  • /ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr is a Yandex.Cloud database with etn01q3ko8sh271beftr as ID deployed in the b1g8skpbljhs03malf3scloud in the ru-central1 region.
  • /local is the default database for custom deployment using Docker.

Configuring connection parameters on the client

For information about how to define connection parameters on the client, see the following articles:

Additional information

A root certificate for TLS

When using an encrypted protocol (gRPC over TLS, or gRPCS), a network connection can only be continued if the client is sure that it receives a response from the genuine server that it is trying to connect to, rather than someone in-the-middle intercepting its request on the network. This is assured by verifications through a chain of trust which requires the client to have a root certificate installed to operate.

The OS that the client runs on already include a set of root certificates from the world’s major certification authorities. However, the YDB cluster owner can use its own CA that is not associated with any of the global ones, which is often the case in corporate environments, and is almost always used for self-hosted deployment of clusters with connection encryption support. In this case, the cluster owner must somehow transfer its root certificate for use on the client side. This certificate may be installed in the operating system’s certificate store where the client runs (manually by a user or by a corporate OS administration team) or built into the client itself (as is the case for Yandex.Cloud in YDB CLI and SDK).

API for getting IAM tokens

For token rotation, the YDB SDK and CLI use a gRPC request to the Yandex.Cloud IAM API IamToken - create. In Refresh Token mode, the token specified in the OAuth parameter is passed in the yandex_passport_oauth_token attribute. In Service Account Key mode, a short-lived JWT token is generated from the specified service account attributes and an encryption key and passed in the jwt property. The source code for generating the JWT is available as part of the SDK (for example, the get_jwt() method in the Python code).

In the YDB SDK and CLI, you can substitute the host used for accessing the API for obtaining tokens. This makes it possible to implement a similar API in corporate contexts.