Connecting to a database
To connect to a YDB database from the YDB CLI or an app running the YDB SDK, specify your endpoint and database path.
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 by way of a network infrastructure as well as for proper network connections. Cloud databases display the endpoint in the management console on the requisite DB page and also normally send it via the cloud provider's CLI. In corporate environments, endpoint names YDB are provided by the administration team or obtained in the internal cloud management console.
Examples:
grpc://localhost:7135is an unencrypted data interchange protocol (gRPC) with the server running on port 7135 of the same host as the client.grpcs://ydb.example.comis an encrypted data interchange protocol (gRPCs) with the server running on the ydb.example.com host on an isolated corporate network and listening for connections on YDB default port 2135.grpcs://ydb.serverless.yandexcloud.net:2135is an encrypted data interchange protocol (gRPCs), public Yandex.Cloud Serverless YDB server at ydb.serverless.yandexcloud.net, port 2135.
Database path
Database path (database) is a string that defines where the queried database is located in the YDB cluster. Has the format and uses the / character as separator. It always starts with a /.
A YDB cluster may have multiple databases deployed, with their paths determined 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 without the 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/etn01q5ko6sh271beftris a Yandex.Cloud database withetn01q3ko8sh271beftras ID deployed in theb1g8skpbljhs03malf3scloud in theru-central1region./localis the default database for custom deployment using Docker.
Connection string
A connection string is a URL-formatted string that specifies the endpoint and path to a database using the following syntax:
<endpoint>?database=<database>
Examples:
grpc://localhost:7135?database=/localgrpcs://ydb.serverless.yandexcloud.net:2135?database=/ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr
Using a connection string is an alternative to specifying the endpoint and database path separately and can be used in tools that support this method.
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-between intercepting its request on the network. This is assured by verifications through a chain of trust, for which you need to install a root certificate on your client.
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-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).