Драйвер JDBC#

Драйвер JDBC Trino позволяет пользователям получать доступ к Trino из приложений на Java, а также из других приложений не на Java, работающих в JVM. Драйвер JDBC используют как настольные, так и серверные приложения, например инструменты отчетности и разработки баз данных.

Драйвер JDBC использует Клиентский протокол поверх HTTP/HTTPS для взаимодействия с координатором в кластере.

Требования#

Драйвер JDBC Trino предъявляет следующие требования:

Java версии 11 или выше. Java 22 или выше рекомендуется для лучшей производительности распаковки.
Всем пользователям, подключающимся к Trino с помощью драйвера JDBC, должен быть предоставлен доступ к запросам таблиц в схеме system.jdbc.
Сетевой доступ по HTTP/HTTPS к координатору кластера Trino.
Сетевой доступ к настроенному объектному хранилищу, если включен Протокол спулинга.

Версия драйвера JDBC должна совпадать с версией кластера Trino или быть новее. Более старые версии обычно работают, но регулярно тестируется только часть комбинаций. Версии до 350 не поддерживаются.

Установка#

Скачайте trino-jdbc-latest.jar и добавьте его в classpath вашего Java-приложения.

Драйвер также доступен из Maven Central:

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

Рекомендуется использовать последнюю версию драйвера JDBC. Список всех доступных версий можно найти в Maven Central Repository. Перейдите в каталог нужной версии и выберите для скачивания файл trino-jdbc-xxx.jar, где xxx — номер версии.

После скачивания необходимо добавить JAR-файл в каталог classpath пользователей на системах, где они будут обращаться к Trino.

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

Регистрация и настройка драйвера#

Обычно приложения автоматически загружают драйверы после добавления их в classpath. Если ваше приложение этого не делает, например некоторые GUI-редакторы SQL, прочитайте этот раздел. Шаги регистрации драйвера JDBC в UI или командной строке зависят от конкретного используемого приложения. Обратитесь к документации вашего приложения.

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

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

Когда драйвер загружен, зарегистрирован и настроен, можно подключаться к Trino из приложения. Поддерживаются следующие форматы JDBC URL:

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

Значение port необязательно, если Trino доступен на HTTP-порту по умолчанию 80 или при SSL=true на HTTPS-порту по умолчанию 443.

Ниже приведен пример JDBC URL для создания подключения:

jdbc:trino://example.net:8080/hive/sales

Этот пример JDBC URL указывает экземпляр Trino, работающий на порту 8080 на example.net, с заданными каталогом hive и схемой sales.

Note

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

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

Драйвер поддерживает различные параметры, которые можно задавать как параметры URL или как свойства, передаваемые в DriverManager. Следующие два примера эквивалентны:

// свойства
String url = "jdbc:trino://example.net:8080/hive/sales";
Properties properties = new Properties();
properties.setProperty("user", "test");
properties.setProperty("password", "secret");
properties.setProperty("SSL", "true");
Connection connection = DriverManager.getConnection(url, properties);

// параметры URL
String url = "jdbc:trino://example.net:8443/hive/sales?user=test&password=secret&SSL=true";
Connection connection = DriverManager.getConnection(url);

Эти способы можно смешивать: часть параметров можно указать в URL, а другие — через свойства. Однако один и тот же параметр нельзя указывать обоими способами.

Справочник параметров#

Имя	Описание
`user`	Имя пользователя для аутентификации и авторизации.
`password`	Пароль для LDAP-аутентификации.
`sessionUser`	Переопределение имени пользователя сеанса, используемое для имперсонации.
`socksProxy`	Хост и порт SOCKS-прокси. Пример: `localhost:1080`
`httpProxy`	Хост и порт HTTP-прокси. Пример: `localhost:8888`
`clientInfo`	Дополнительная информация о клиенте.
`clientTags`	Клиентские теги для выбора групп ресурсов. Пример: `abc,xyz`
`path`	Задает SQL path по умолчанию для сеанса. Полезно для задания расположения каталога и схемы для Catalog user-defined functions.
`traceToken`	Токен трассировки для корреляции запросов между системами.
`source`	Имя источника для запроса Trino. Этот параметр следует предпочитать `ApplicationName`. Поэтому он имеет приоритет над `ApplicationName` и/или `applicationNamePrefix`.
`applicationNamePrefix`	Префикс, добавляемый к любому указанному свойству клиентской информации `ApplicationName`, которое используется для задания имени источника запроса Trino, если параметр `source` не задан. Если не заданы ни это свойство, ни `ApplicationName`, ни `source`, имя источника запроса — `trino-jdbc`.
`accessToken`	Токен доступа JWT для аутентификации на основе токена.
`SSL`	Установите `true`, чтобы использовать TLS/HTTPS для подключений.
`SSLVerification`	Метод проверки TLS. Есть три режима: `FULL` (по умолчанию), `CA` и `NONE`. Для `FULL` выполняется обычная проверка TLS. Для `CA` проверяется только CA, а несовпадение имени хоста допускается. Для `NONE` проверка не выполняется.
`SSLKeyStorePath`	Используйте только при подключении к кластеру Trino, где включена аутентификация по сертификату. Задает путь к файлу PEM или JKS, который должен содержать сертификат, доверенный кластером Trino, к которому выполняется подключение.
`SSLKeyStorePassword`	Пароль для KeyStore, если он есть.
`SSLKeyStoreType`	Тип KeyStore. Тип по умолчанию предоставляется свойством безопасности Java `keystore.type`, либо используется `jks`, если такого свойства нет.
`SSLUseSystemKeyStore`	Установите `true`, чтобы автоматически использовать системный KeyStore на основе операционной системы. Поддерживаемые ОС — Windows и macOS. В Windows выбирается KeyStore `Windows-MY`. В macOS выбирается KeyStore `KeychainStore`. Для других ОС загружается Java KeyStore по умолчанию. Спецификацию KeyStore можно переопределить с помощью `SSLKeyStoreType`.
`SSLTrustStorePath`	Расположение файла Java TrustStore, используемого для проверки сертификатов HTTPS-сервера.
`SSLTrustStorePassword`	Пароль для TrustStore.
`SSLTrustStoreType`	Тип TrustStore. Тип по умолчанию предоставляется свойством безопасности Java `keystore.type`, либо используется `jks`, если такого свойства нет.
`SSLUseSystemTrustStore`	Установите `true`, чтобы автоматически использовать системный TrustStore на основе операционной системы. Поддерживаемые ОС — Windows и macOS. В Windows выбирается TrustStore `Windows-ROOT`. В macOS выбирается TrustStore `KeychainStore`. Для других ОС загружается Java TrustStore по умолчанию. Спецификацию TrustStore можно переопределить с помощью `SSLTrustStoreType`.
`hostnameInCertificate`	Ожидаемое имя хоста в сертификате, представленном сервером Trino. Применимо только при включенной полной проверке SSL.
`KerberosRemoteServiceName`	Имя службы Kerberos координатора Trino. Этот параметр обязателен для аутентификации Kerberos.
`KerberosPrincipal`	Principal, используемый при аутентификации на координаторе Trino.
`KerberosUseCanonicalHostname`	Использовать каноническое имя хоста координатора Trino для principal службы Kerberos: сначала имя хоста разрешается в IP-адрес, затем выполняется обратный DNS-поиск для этого IP-адреса. Включено по умолчанию.
`KerberosServicePrincipalPattern`	Шаблон principal службы Kerberos координатора Trino. По умолчанию — `${SERVICE}@${HOST}`. `${SERVICE}` заменяется значением `KerberosRemoteServiceName`, а `${HOST}` заменяется именем хоста координатора (после каноникализации, если она включена).
`KerberosConfigPath`	Файл конфигурации Kerberos.
`KerberosKeytabPath`	Файл keytab Kerberos.
`KerberosCredentialCachePath`	Кэш учетных данных Kerberos.
`KerberosDelegation`	Установите `true`, чтобы использовать токен из существующего контекста Kerberos. Это позволяет клиенту использовать аутентификацию Kerberos без передачи Keytab или кэша учетных данных. По умолчанию — `false`.
`extraCredentials`	Дополнительные учетные данные для подключения к внешним службам, заданные как список пар ключ-значение. Например, `foo:bar;abc:xyz` создает учетные данные с именем `abc` и значением `xyz`, а также учетные данные с именем `foo` и значением `bar`.
`roles`	Роли авторизации для каталогов, заданные как список пар ключ-значение для каталога и роли. Например, `catalog1:roleA;catalog2:roleB` задает `roleA` для `catalog1` и `roleB` для `catalog2`.
`sessionProperties`	Свойства сеанса для системы и каталогов, заданные как список пар ключ-значение. Например, `abc:xyz;example.foo:bar` задает системное свойство `abc` в значение `xyz` и свойство `foo` для каталога `example` в значение `bar`.
`extraHeaders`	HTTP-заголовки, добавляемые к аутентифицированным HTTP-запросам, заданные как список пар ключ-значение. Например, `X-Trino-Foo:xyz;X-Trino-Bar:bar` отправляет заголовок `X-Trino-Foo` со значением `xyz` и заголовок `X-Trino-Bar` со значением `bar`. Заголовки протокола, такие как `X-Trino-User`, нельзя переопределить с помощью этого параметра.
`externalAuthentication`	Установите `true`, если хотите использовать внешнюю аутентификацию через OAuth 2.0-аутентификация. Для аутентификации с поставщиком удостоверений (IdP), настроенным для координатора Trino, используется локальный веб-браузер.
`externalAuthenticationTokenCache`	Позволяет разделять токены внешней аутентификации между разными подключениями для одного и того же аутентифицированного пользователя, пока кэш не будет инвалидирован, например при перезапуске клиента или перезагрузке драйвера JDBC загрузчиком классов. По умолчанию отключено со значением `NONE`. Чтобы включить, задайте значение `MEMORY`. Если драйвер JDBC используется в общем режиме разными пользователями, первый зарегистрированный токен сохраняется и аутентифицирует всех пользователей.
`disableCompression`	Отключать ли HTTP-сжатие. По умолчанию — `false`.
`disallowLocalRedirect`	Должен ли клиент отклонять перенаправления на localhost, link-local или site-local IP-адреса. По умолчанию — `false`.
`assumeLiteralUnderscoreInMetadataCallsForNonConformingClients`	Если включено, шаблоны имен, передаваемые в методы `DatabaseMetaData`, трактуются как литеральные подчеркивания. Это можно использовать как обходной путь для приложений, которые не экранируют имена схем или таблиц при передаче их в методы `DatabaseMetaData` как шаблоны имен схем или таблиц.
`timezone`	Задает часовой пояс сеанса с помощью переданного часового пояса. По умолчанию используется часовой пояс JVM, запускающей драйвер JDBC.
`explicitPrepare`	По умолчанию — `true`. Если установлено `false`, подготовленные операторы выполняются вызовом одного запроса `EXECUTE IMMEDIATE` вместо стандартного `PREPARE <statement>` с последующим `EXECUTE <statement>`. Это снижает сетевые накладные расходы, использует меньшие HTTP-заголовки и требует Trino 431 или новее.
`encoding`	Задает кодировку при использовании протокола спулинга. Допустимые значения: JSON со сжатием Zstandard `json+zstd` (рекомендуется), JSON со сжатием LZ4 `json+lz4` и несжатый JSON `json`. По умолчанию используется кодировка, настроенная в кластере.
`validateConnection`	По умолчанию — `false`. Если установлено `true`, подключение и учетные данные проверяются при создании подключения и при вызове `java.sql.Connection.isValid(int)`.

Протокол спулинга#

Драйвер JDBC Trino автоматически использует протокол спулинга для повышения пропускной способности при клиентском взаимодействии с повышенными требованиями к передаче данных, если в кластере настроен Протокол спулинга.

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

Процесс JVM, использующий драйвер JDBC, должен иметь сетевой доступ к объектному хранилищу спулинга.