JDBC драйвер#

Пользователи CedrusData могут использовать оригинальный JDBC драйвер Trino для подключения к кластеру из Java-приложений и программ, которые поддерживают JDBC.

Ниже приведена документация JDBC драйвера Trino.

Требования#

  • JDBC драйвер Trino требует Java версии 8 и выше.

  • Все пользователи, которые подключаются к CedrusData через JDBC драйвер, должны иметь доступ на чтение к схеме system.jdbc.

Рекомендовано использовать JDBC драйвер той же major версии, что и кластер CedrusData. Более старые версии могут работать, но только незначительная их часть регулярно проверяется на совместимость с текущей версией. Версии до 350 не поддерживаются.

Установка#

JDBC драйвер Trino представляет собой JAR-файл, который вы можете скачать из Maven Central или получить из архива CedrusData из директории jdbc/.

После получения JDBC драйвера, добавьте его в ваше приложение. Процедура регистрации зависит от приложения. Если вы регистрируете драйвер в стороннем приложении (например, Apache Superset или Tableau), вам необходимо следовать инструкции по установке JDBC драйверов для данного приложения.

Если вы разрабатываете собственное Java-приложение, вам необходимо добавить JAR файл в classpath. Например, если вы используете систему сборки Maven, добавьте следующую зависимость к своему проекту:

<dependency>
    <groupId>io.trino</groupId>
    <artifactId>trino-jdbc</artifactId>
    <version>458</version>
</dependency>

Подключение#

После того как JDBC драйвер зарегистрирован в приложении, вы можете использовать его для подключения к CedrusData.

JDBC драйвер Trino поддерживает следующие форматы URL, где host:port это адрес coordinator узла:

jdbc:trino://host:port
jdbc:trino://host:port/catalog
jdbc:trino://host:port/catalog/schema

Значение port является необязательным. Если portне указан, то будет использован порт 80 для протокола HTTP и порт 443 для протокола HTTPS.

Вы можете указать в URL дополнительные параметры конфигурации в формате key=value. Полный список доступных параметров конфигурации приведен ниже.

jdbc:trino://host:port?key1=value2&key2=value2
jdbc:trino://host:port/catalog?key1=value2&key2=value2
jdbc:trino://host:port/catalog/schema?key1=value2&key2=value2

JDBC драйвер Trino требует, чтобы при подключении всегда было указано имя пользователя, даже если аутентификация CedrusData отключена. В противном случае вы получите следующую ошибку:

Authentication failed: Basic authentication or X-Trino-User must be sent

Ниже приведен пример Java-кода для подключения к coordinator узлу, запущенному на локальном компьютере на порту 8080, с использованием каталога tpch и схемы sf1 по умолчанию:

// Передача параметров через объект Properties.
String url = "jdbc:trino://localhost:8080/tpch/sf1";
Properties properties = new Properties();
properties.setProperty("user", "test");
Connection connection = DriverManager.getConnection(url, properties);

// Передача параметров через URL.
String url = "jdbc:trino://localhost:8080/tpch/sf1?user=test";
Connection connection = DriverManager.getConnection(url);

Примечание

Современные приложения обычно не требуют имя класса JDBC драйвера. Если ваше приложение запрашивает имя класса JDBC драйвера, используйте io.trino.jdbc.TrinoDriver.

Параметры подключения#

Общие параметры#

Имя

Описание

user

Имя пользователя CedrusData. Если безопасность CedrusData отключена, необходимо предоставить произвольное непустое значение.

password

Пароль пользователя CedrusData.

sessionUser

Имя пользователя сессии для имперсонации.

httpProxy

Адрес HTTP proxy в формате host:port. Например: localhost:8888.

socksProxy

Адрес SOCKS proxy в формате host:port. Например: localhost:1080.

clientInfo

Дополнительная информация о клиенте.

clientTags

Теги клиента для выбора групп ресурсов. Например: abc,xyz

path

Устанавливает SQL path по умолчанию для текущей сессии.

traceToken

Токен трассировки для сопоставления запросов между системами.

source

Имя источника запроса к CedrusData. Данный параметр имеет приоритет перед ApplicationName и applicationNamePrefix.

applicationNamePrefix

Префикс, который будет добавлен к свойству ApplicationName, которое используется для указания имени источника запроса к CedrusData, если параметр source не установлен. Если ни ApplicationName, ни source не установлены, имя источника будет автоматически установлено в trino-jdbc.

accessToken

Токен доступа для JWT.

extraCredentials

Extra credentials для подключения к источникам данных. Представляет собой список пар ключ-значение. Например, строка foo:bar;abc:xyz создает два extra credential c именами foo и abc и значениями bar и xyz, соответственно.

roles

Роли авторизации для работы с каталогами CedrusData. Представляет собой список пар ключ-значение в формате каталог:роль. Например, значение catalog1:roleA;catalog2:roleB задает роль roleA для каталога catalog1 и роль roleB для каталога catalog2.

sessionProperties

Параметры сессии SQL запросов CedrusData. Представляет собой список пар ключ-значение. Например, abc:xyz;example.foo:bar задает глобальное свойство abc со значением xyz и свойство foo со значением bar для каталога example.

externalAuthentication

Установите в true для использования внешней аутентификации с помощью OAuth 2.0 аутентификация. Используйте браузер для аутентификации в identity provider (IdP), был сконфигурирован для координатора CedrusData.

externalAuthenticationTokenCache

Позволяет переиспользовать внешние токены аутентификации между несколькими JDBC подключениями одного и того же пользователя до тех пор, пока не произойдет инвалидация токена (например, при перезапуске клиента). Допустимые значения: NONE (значение по умолчанию) - переиспользование токенов отключено; MEMORY - переиспользование токен включено. Если JDBC драйвер используют несколько пользователей, первый зарегистрированный токен аутентифицирует всех пользователей.

disableCompression

Отключить компрессию передаваемых данных.

assumeLiteralUnderscoreInMetadataCallsForNonConformingClients

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

timezone

Задает time zone для сессии (см. документацию Java). По умолчанию равна time zone JVM, в которой запущен JDBC драйвер.

explicitPrepare

Значение по умолчанию: true. Если false, prepared statement будет выполнен с помощью одной команды EXECUTE IMMEDIATE. В противном случае prepared statement будет выполнен с помощью двух команд PREPARE <statement> и EXECUTE <statement>. Значение false уменьшает накладные расходы на сетевое взаимодействие, но требует CedrusData 431-1 и выше.

Параметры SSL#

Имя

Описание

SSL

Использовать TLS/HTTPS для подключения.

SSLVerification

Имя метода TLS верификации. Допустимые значения: FULL (значение по умолчанию), CA, NONE. В режиме FULL TLS верификация осуществляется в полном объеме. В режиме CA осуществляется только верификация CA, допустимо несовпадение hostname. В режиме NONE верификация отключена.

SSLKeyStorePath

Путь к файлу PEM или JKS, который содержит доверенный сертификат для подключения к кластеру CedrusData. Используйте данный параметр только при подключении к кластеру CedrusData в котором включена certificate authentication.

SSLKeyStorePassword

Пароль KeyStore (при наличии).

SSLKeyStoreType

Тип KeyStore. Значение по умолчанию равно значению параметра Java keystore.type или jks в случае отсутствия первого.

SSLUseSystemKeyStore

Автоматически использовать системный KeyStore операционной системы. Для Windows используется KeyStore Windows-MY. Для macOS используется KeyStore KeychainStore. Для других операционных систем используется KeyStore Java по умолчанию. Спецификация KeyStore может быть переопределена с помощью параметра SSLKeyStoreType.

SSLTrustStorePath

Путь к файлу TrustStore для проверки серверных HTTPS сертификатов.

SSLTrustStorePassword

Пароль к файлу TrustStore.

SSLTrustStoreType

Тип TrustStore. Значение по умолчанию равно значению параметра Java keystore.type или jks в случае отсутствия первого.

SSLUseSystemTrustStore

Автоматически использовать системный TrustStore операционной системы. Для Windows используется TrustStore Windows-ROOT. Для macOS используется TrustStore KeychainStore. Для других операционных систем используется TrustStore Java по умолчанию. Спецификация TrustStore может быть переопределена с помощью параметра SSLTrustStoreType.

hostnameInCertificate

Ожидаемый hostname сертификата, предоставляемого сервером CedrusData. Применимо только при SSLVerification=FULL.

Параметры Kerberos#

Для авторизации с помощью Kerberos, необходимо задать principal координатора CedrusData, и principal пользователя, от имени которого будет происходить аутентификация.

В процессе авторизации JDBC-драйвер формирует principal координатора CedrusData в host-based формате primary@instance (см. компоненты principal Kerberos). Например, если principal координатора равен cedrus/coordinator.example.com@EXAMPLE.COM, то его primary это cedrus, а его instance это coordinator.example.com. В этом случае для успешной аутентификации JDBC-драйвер должен разрешить principal координатора в строку cedrus@coordinator.example.com. Разрешение principal координатора происходит следующим образом:

  1. JDBC-драйвер берет паттерн из параметра KerberosServicePrincipalPattern. Значение по умолчанию: ${SERVICE}@${HOST}. В большинстве случаев вам не нужно его изменять. Исключения составляют только случаи, когда происходит некорректное разрешение имени сервера координатора, как объяснено ниже.

  2. Компонент паттерна ${SERVICE} безусловно заменяется значением параметра KerberosRemoteServiceName. Если параметр KerberosRemoteServiceName не задан, Kerberos не будет использован для аутентификации. Таким образом, KerberosRemoteServiceName соответствует primary части principal.

  3. Компонент паттерна ${HOST} будет заменен именем сервера координатора. Если включен параметр KerberosUseCanonicalHostname (включен по умолчанию), предварительно будет произведена попытка каноникализации адреса сервера. Например, вы подключаетесь к координатору по адресу coordinator.intranet или 172.16.0.5. При включенном параметре KerberosUseCanonicalHostname, JDBC-драйвер использует DNS для преобразования текущего адреса координатора в IP-адрес, а потом для преобразования IP-адреса в канонический адрес, например, coordinator.example.com. Если каноникализация отключена, адрес сервера будет использован как есть, что в ряде случаев может привести к некорректному поведению Kerberos.

В результате перечисленных преобразований обязательно должна быть получена строка вида primary@instance. Следуйте рекомендациям ниже, чтобы избежать ошибок аутентификации:

  • Отсутствие компонента @instance в имени principal координатора может привести к неочевидным ошибкам, так как в этом случае Java-машина может попробовать автоматически подставить в качестве instance имя клиентского узла, что почти всегда приведет к ошибке авторизации. Например, если вы подключаетесь к CedrusData с машины с именем client.example.com, вы можете получить некорректный principal координатора вида cedrus@client.example.com.

  • В редких случаях вы можете работать в окружении, в котором координатор CedrusData не имеет валидного доменного имени. Например, такое может встречаться в тестовых окружениях. В этом случае, вы можете заменить ${HOST} в паттерне на желаемое значение. Например, если реальный principal координатора равен cedrus/coordinator.example.com@EXAMPLE.COM, вы можете задать KerberosServicePrincipalPattern=${SERVICE}@coordinator.example.com и KerberosRemoteServiceName=cedrus. Это приведет к разрешению principal координатора в cedrus@coordinator.example.com.

Реальная аутентификация в Kerberos происходит с использованием значения principal из KerberosPrincipal. Это же значение будет использовано в качестве имени пользователя CedrusData (с учетом Сопоставление пользователей). Для подключения по JDBC вы также должны указать имя пользователя (параметр user). В большинстве случаев имя пользователя будет совпадать со значением KerberosPrincipal. Если значения отличаются, при получении SQL-запроса координатор CedrusData будет осуществлять имперсонацию: запрос будет запущен пользователем KerberosPrincipal, но от имени пользователя переданного в параметре user.

Имя

Описание

KerberosRemoteServiceName

Имя сервиса координатора CedrusData. Обязателен для аутентификации через Kerberos.

KerberosUseCanonicalHostname

Использовать канонический сетевой адрес координатора CedrusData при формировании principal координатора. Включено по умолчанию.

KerberosServicePrincipalPattern

Паттерн service principal паттерн координатора CedrusData. Значение по умолчанию: ${SERVICE}@${HOST}. ${SERVICE} будет заменен на значение параметра KerberosRemoteServiceName, ${HOST} будет заменен на адрес сетевой координатора.

KerberosPrincipal

Principal пользователя, который будет использован для аутентификации в Kerberos.

KerberosConfigPath

Путь к файлу конфигурации Kerberos. Обычно данный файл расположен по пути /etc/krb5.conf

KerberosKeytabPath

Путь к keytab файлу Kerberos. Keytab должен содержать ключ пользователя, указанного в параметре KerberosPrincipal.

KerberosCredentialCachePath

Опциональный путь к Kerberos credential cache.

KerberosDelegation

Установите значение true, чтобы использовать токен из текущего контекста Kerberos. Это позволяет клиенту использовать аутентификацию Kerberos без передачи Keytab или credential cache. Значение по умолчанию: false.

KerberosConstrainedDelegation

Передавать объект GssCredential как свойство драйвера.