Соединение с БД

Для соединения с БД YDB из YDB CLI или приложения, использующего YDB SDK, необходимо указать эндпоинт и путь базы данных.

Эндпоинт

Эндпоинт (endpoint) - строка в формате protocol://host:port, предоставляемая владельцем кластера YDB для корректной маршрутизации запросов клиента к его базам данных через сетевую инфраструктуру и установки сетевого соединения. Для облачных баз данных endpoint показывается в консоли управления на странице требуемой БД, а также обычно может быть получен через CLI облачного поставщика. В корпоративных окружениях имена эндпоинтов YDB предоставляются командой администраторов или также могут быть получены в консоли управления внутренним облаком.

Примеры:

  • grpc://localhost:7135 — протокол обмена данными без шифрования (gRPC), сервер запущен на том же хосте что и клиент, принимает соединения на порту 7135.
  • grpcs://ydb.example.com — протокол обмена данными с шифрованием (gRPCs), сервер запущен на хосте ydb.example.com в изолированной корпоративной интрасети, принимает соединения на порту YDB по умолчанию 2135.

Путь базы данных

Путь базы данных (database) - строка, определяющая где на кластере YDB находится база данных, к которой адресован запрос. Имеет структуру пути к файлу, с использованием символа / в качестве разделителя. Начинается всегда с символа /.

На кластере YDB может быть развернуто множество баз данных, и их пути определяются конфигурацией кластера. Как и эндпоинт, для облачных баз данных database показывается в консоли управления на странице требуемой БД, а также обычно может быть получен через CLI облачного поставщика.

При использовании облачных решений базы данных на кластере YDB создаются и размещаются в режиме самообслуживания, не требуя участия владельца и администраторов кластера.

Важно

Приложения не должны как-либо интерпретировать количество и значение каталогов в database, так как они определяются конфигурацией кластера YDB. Например, при работе с сервисом YDB в Yandex.Cloud database сейчас имеет структуру region_name/cloud_id/database_id, однако этот формат может быть изменен в будущем для новых БД.

Примеры:

  • /ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr — база данных Yandex.Cloud с идентификатором etn01q3ko8sh271beftr в облаке b1g8skpbljhs03malf3s, развернутая в регионе ru-central1.
  • /local — база данных по умолчанию при самостоятельном развертывании с использованием Docker.

Строка соединения

Строка соединения (connection string) — это строка в формате URL, указывающая эндпоинт и путь к базе данных, с использованием следующего синтаксиса:

<endpoint>?database=<database>

Примеры:

  • grpc://localhost:7135?database=/local
  • grpcs://ydb.serverless.yandexcloud.net:2135?database=/ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr

Использование строки соединения является альтернативой раздельному указанию эндпоинта и пути к базе данных и может применяться в тех инструментах, которые поддерживают данный метод.

Корневой сертификат для TLS

При использовании протокола с шифрованием (gRPC over TLS, или grpcs) продолжение сетевого соединения возможно только в том случае, если клиент уверен в том, что ему действительно отвечает подлинный сервер, с которым он пытается установить соединение, а не кто-то посередине, перехвативший запрос в сети. Это обеспечивается проверкой через цепочки доверия, для работы которой на клиенте должен быть установлен т.н. корневой сертификат.

В состав операционных систем, на которых запускается клиент, уже входит набор корневых сертификатов от основных мировых центров сертификации. Однако, владелец кластера YDB может использовать свой центр сертификации, не связанный ни с одним из мировых, что часто встречается в корпоративных окружениях, и почти всегда применяется при самостоятельном развертывании кластеров с поддержкой шифрования на соединениях. В этом случае владелец кластера должен каким-либо образом передать свой корневой сертификат для использования на стороне клиента. Такой сертификат может быть установлен в хранилище сертификатов операционной системы, где запускается клиент (вручную пользователем или корпоративной командой администраторов ОС), или встроен в состав самого клиента (как это сделано для Yandex.Cloud в YDB CLI и SDK).

Предыдущая