Соединение с БД
Для соединения с БД 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).