Databricks JDBC Driver (OSS)

Статья
01/21/2025

Внимание

Этот драйвер находится в общедоступной предварительной версии и будет доступен как открытый исходный код, когда он станет общедоступным (GA).

Databricks JDBC (OSS), последняя версия драйвера, позволяет подключать такие средства, как DataGrip, DBeaverи SQL Workbench/J к Azure Databricks через JDBC, стандартную спецификацию для доступа к системам управления базами данных.

Этот драйвер реализовал API JDBC и предоставляет основные функции, включая OAuth, Cloud Fetch и такие функции, как прием томов каталога Unity. Он выполняет собственный режим запроса и поддерживает собственный параметризованный запрос и может выполняться с помощью API выполнения инструкций, что обеспечивает полезный компонент хранения результатов запроса или Thrift.

В этой статье содержатся сведения об установке и использовании драйвера JDBC Databricks (OSS). Сведения о драйвере JDBC, отличном от OSS Databricks, см. в разделе Databricks JDBC Driver.

Требования

Чтобы использовать драйвер JDBC Databricks (OSS), необходимо выполнить следующие требования:

Среда выполнения Java (JRE) 11.0 или более поздней версии. Тестирование CI поддерживается в JRE 11, 17 и 21.

Примечание.

В результате изменения В JDK 16, вызвавшей проблему совместимости с библиотекой Apache Arrow, используемой драйвером JDBC, ошибки среды выполнения могут возникать при использовании драйвера JDBC с JDK 16 или более поздней версии. Чтобы предотвратить эти ошибки, перезапустите приложение или драйвер с помощью следующей команды JVM:

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

Установка драйвера

Драйвер JDBC (OSS) Databricks публикуется в репозитории Maven.

Чтобы установить драйвер, можно выполнить любое из следующих действий:

Для проектов Maven добавьте в файл проекта pom.xml следующую зависимость, чтобы указать Maven автоматически скачать драйвер JDBC с указанной версией:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
Для проектов Gradle добавьте в файл сборки проекта следующую зависимость, чтобы указать Gradle автоматически скачать драйвер JDBC с указанной версией:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Чтобы просмотреть синтаксис зависимостей для других типов проектов и получить последнюю версию драйвера JDBC Databricks (OSS), см. репозитория Maven.

Настройка URL-адреса подключения

Чтобы подключиться к рабочей области Azure Databricks с помощью драйвера JDBC, необходимо указать URL-адрес подключения JDBC, включающий различные параметры подключения, такие как имя узла сервера рабочей области Azure Databricks, параметры вычислительного ресурса и учетные данные проверки подлинности для подключения к рабочей области.

Вы можете задать значение этих свойств по URL-адресу подключения JDBC, задать и передать их в метод DriverManager.getConnectionили сочетание обоих. Сведения о том, как лучше всего подключиться с помощью конкретного приложения, клиента, пакета SDK, API или средства SQL, см. в документации поставщика.

URL-адрес подключения JDBC должен иметь следующий формат. Свойства являются нечувствительными к регистру.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Кроме того, укажите параметры с помощью java.util.Properties класса или сочетания:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Элементы URL-адреса подключения описаны в следующей таблице. Дополнительные сведения о дополнительных свойствах, включая свойства проверки подлинности, см. в следующих разделах. Элементы и свойства URL-адреса не учитывает регистр.

Элемент URL-адреса или свойство	Description
`<server-hostname>`	Значение имени узла сервера в Azure Databricks.
`<port>`	Значение порта вычислительного ресурса Azure Databricks. Значение по умолчанию — `443`.
`<schema>`	Имя схемы. Кроме того, можно задать свойство `ConnSchema`. См . свойства подключения.
`httpPath`	Значение HTTP-пути вычислительного ресурса Azure Databricks. Соединитель формирует HTTP-адрес для подключения, добавляя `httpPath` значение к узлу и порту, указанному в URL-адресе подключения. Например, чтобы подключиться к HTTP-адресу, используйте следующий URL-адрес `http://localhost:10002/cliservice`подключения: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Чтобы получить URL-адрес подключения JDBC для кластера Azure Databricks :

Выполните вход в рабочую область Azure Databricks.
На боковой панели щелкните " Вычисления", а затем щелкните имя целевого кластера.
На вкладке "Конфигурация" разверните дополнительные параметры.
Перейдите на вкладку JDBC/ODBC .
Скопируйте URL-адрес JDBC для использования в качестве URL-адреса подключения JDBC или создайте URL-адрес из значений в хосте сервера, портеи поле HTTP-пути.

Чтобы получить URL-адрес подключения JDBC для склада Databricks SQL:

Выполните вход в рабочую область Azure Databricks.
На боковой панели щелкните "Хранилища SQL", а затем щелкните имя целевого хранилища.
Перейдите на вкладку сведений о подключении.
Скопируйте URL-адрес JDBC для использования в качестве URL-адреса подключения JDBC или создайте URL-адрес из значений в хосте сервера, портеи поле HTTP-пути.

Проверка подлинности драйвера

Подключение драйвера JDBC можно пройти проверку подлинности с помощью одного из следующих механизмов проверки подлинности:

Проверка подлинности пользователей и компьютеров (U2M) OAuth (рекомендуется)
Проверка подлинности на компьютере (M2M) OAuth
Личный маркер доступа Azure Databricks

Проверка подлинности пользователей и компьютеров OAuth (U2M)

Драйвер JDBC поддерживает проверку подлинности пользователя на компьютере OAuth (U2M) для входа в режиме реального времени и согласия на проверку подлинности целевой учетной записи пользователя Databricks. Это также называется проверкой подлинности OAuth на основе браузера.

Azure Databricks создал идентификатор databricks-sql-jdbc клиента OAuth для клиентов. Это также идентификатор клиента OAuth по умолчанию, используемый в драйвере JDBC. Чтобы настроить проверку подлинности OAuth U2M, просто добавьте следующие свойства в существующий URL-адрес подключения или java.util.Properties объект JDBC:

Свойство	Значение
`AuthMech`	`11`
`Auth_Flow`	`2`

Проверка подлинности на компьютере (M2M) OAuth

Драйвер JDBC поддерживает проверку подлинности OAuth на компьютере (M2M) с помощью субъекта-службы Azure Databricks. Это также называется аутентификация OAuth 2.0 по учетным данным клиента. Ознакомьтесь с проверкой подлинности доступа к Azure Databricks с помощью субъекта-службы с помощью OAuth (OAuth M2M).

Чтобы настроить проверку подлинности учетных данных клиента OAuth M2M или OAuth 2.0:

Создайте управляемый субъект-службу идентификатора Microsoft Entra, а затем назначьте его учетным записям Azure Databricks и рабочим областям. Дополнительные сведения см. в разделе "Управление субъектами-службами".

Внимание

Драйвер JDBC Databricks (OSS) поддерживает использование секретов OAuth в Azure Databricks для аутентификации с помощью учетных данных клиента OAuth M2M или OAuth 2.0. Секреты идентификатора Microsoft Entra не поддерживаются.
Создайте секрет OAuth Azure Databricks для субъекта-службы. Для этого смотрите , чтобы вручную сгенерировать и использовать токены доступа для аутентификации OAuth M2M.
Предоставьте субъекту-службе доступ к кластеру или хранилищу. См . сведения о разрешениях вычислений или управлении хранилищем SQL.

Добавьте следующие свойства в существующий URL-адрес или java.util.Properties объект подключения JDBC:

Свойство	Значение
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Значение идентификатора приложения (клиента) субъекта-службы.
`OAuth2Secret`	Секрет OAuth субъекта-службы Azure Databricks. (Секреты идентификатора Microsoft Entra не поддерживаются для проверки подлинности клиента OAuth M2M или OAuth 2.0.0.)

Личный маркер доступа Azure Databricks

Чтобы проверить подлинность подключения драйвера JDBC с помощью личного маркера доступа Azure Databricks, добавьте следующие свойства в URL-адрес подключения или java.util.Properties объект JDBC:

Свойство	Значение
`AuthMech`	`3`
`user`	Значение `token`в виде строки.
`PWD` или `password`	Значение маркера личного доступа Azure Databricks в виде строки.

Свойства подключения

Следующие дополнительные свойства подключения поддерживаются драйвером JDBC. Свойства являются нечувствительными к регистру.

Свойство	Значение по умолчанию	Description
`AuthMech`	Обязательное поле	Механизм аутентификации, где `3` указывает, что механизм — это личный токен доступа Azure Databricks, а `11` указывает, что механизм — токены OAuth 2.0. Для каждого механизма требуются дополнительные свойства. См. статью "Проверка подлинности драйвера".
`Auth_Flow`	`0`	Поток проверки подлинности OAuth2 для подключения драйвера. Это свойство является обязательным, если `AuthMech` имеет значение `11`.
`SSL`	`1`	Указывает, взаимодействует ли соединитель с сервером Spark через сокет с поддержкой SSL.
`ConnCatalog` или `catalog`	`SPARK`	Имя используемого каталога по умолчанию.
`ConnSchema` или `schema`	`default`	Имя используемой схемы по умолчанию. Это можно указать, заменив `<schema>` в URL-адресе именем схемы, используемой или задав свойство `ConnSchema` имя используемой схемы.
`ProxyAuth`	`0`	Если задано значение `1`, драйвер использует пользователя и пароль проверки подлинности прокси-сервера, представленный `ProxyUID` и `ProxyPwd`.
`ProxyHost`	`null`	Строка, представляющая имя узла прокси-сервера, используемого при `UseProxy` также имеет значение `1`.
`ProxyPort`	`null`	Целое число, представляющее номер прокси-порта, который следует использовать, если `UseProxy` также задано значение `1`.
`ProxyUID`	`null`	Строка, представляющая имя пользователя для аутентификации через прокси-сервер, когда `ProxyAuth` и `UseProxy` также установлены на `1`.
`ProxyPwd`	`null`	Строка, представляющая пароль, используемый для аутентификации через прокси-сервер, когда `ProxyAuth` и `UseProxy` также установлены в `1`.
`UseProxy`	`0`	Если задано значение `1`, драйвер использует предоставленные параметры прокси-сервера (например, `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`и `ProxyUID`).
`UseSystemProxy`	`0`	Если задано значение `1`, драйвер использует параметры прокси-сервера, заданные на уровне системы. Если в URL-адресе подключения заданы дополнительные свойства прокси-сервера, эти дополнительные свойства прокси-сервера переопределяют те, которые были заданы на уровне системы.
`UseCFProxy`	`0`	Если задано значение `1`, драйвер использует параметры прокси-сервера для извлечения данных из облака, если они указаны; в противном случае он использует обычный прокси-сервер.
`CFProxyAuth`	`0`	Если задано значение `1`, драйвер использует пользователя и пароль проверки подлинности прокси-сервера, представленный `CFProxyUID` и `CFProxyPwd`.
`CFProxyHost`	`null`	Строка, представляющая имя узла прокси-сервера, используемого при `UseCFProxy` также имеет значение `1`.
`CFProxyPort`	`null`	Целое число, представляющее номер прокси-порта, который следует использовать, если `UseCFProxy` также задано значение `1`.
`CFProxyUID`	`null`	Строка, представляющая имя пользователя для аутентификации через прокси-сервер, когда `CFProxyAuth` и `UseCFProxy` также установлены на `1`.
`CFProxyPwd`	`null`	Строка, представляющая пароль, используемый для аутентификации через прокси-сервер, когда `CFProxyAuth` и `UseCFProxy` также установлены в `1`.
`AsyncExecPollInterval`	`200`	Время в миллисекундах между каждым опросом для состояния асинхронного выполнения запроса. Асинхронный относится к тому, что вызов RPC, используемый для выполнения запроса к Spark, является асинхронным. Это не означает, что поддерживаются асинхронные операции JDBC.
`UserAgentEntry`	`browser`	Запись пользовательского агента, включаемая в HTTP-запрос. Это значение имеет следующий формат: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Следует ли драйверУ JDBC использовать клиент Thrift для подключения к кластеру всех целей. Значение по умолчанию работает для хранилищ SQL.

Свойства конфигурации SQL

Следующие свойства конфигурации SQL поддерживаются драйвером JDBC. Они также описаны в параметрах конфигурации . Свойства являются нечувствительными к регистру.

Свойство	Значение по умолчанию	Description
`ansi_mode`	`TRUE`	Следует ли включить строгое поведение ANSI SQL для определенных функций и правил приведения.
`enable_photon`	`TRUE`	Следует ли включить векторную подсистему запросов Фотона.
`legacy_time_parser_policy`	`EXCEPTION`	Методы, используемые для анализа и форматирования дат и меток времени. Допустимые значения: `EXCEPTION`, `LEGACY`и `CORRECTED`.
`max_file_partition_bytes`	`128m`	Максимальное количество байтов, которое можно упаковать в один раздел при чтении из источников, основанных на файлах. Параметр может быть любым положительным целым числом и при необходимости включать такие меры, как `b` (байты) `k` или `kb` (1024 байта).
`read_only_external_metastore`	`false`	Определяет, обрабатывается ли внешнее хранилище метаданных как доступное только для чтения.
`statement_timeout`	`172800`	Задает время ожидания инструкции SQL от 0 до 172800 секунд.
`timezone`	`UTC`	Задайте локальный часовой пояс. Идентификаторы регионов в форме `area/city`, такие как Америка/Los_Angeles или смещения зоны в формате (+\|-)HH, (+\|-)HH:mm или (+\|-)HH:mm:ss, например -08, +01:00 или -13:33:33:33. Кроме того, `UTC` поддерживается в качестве псевдонима для +00:00
`use_cached_result`	`true`	Если это возможно, Databricks SQL кэширует и повторно использует результаты.

Свойства ведения журнала

Следующие свойства ведения журнала поддерживаются драйвером JDBC. Свойства являются нечувствительными к регистру.

Свойство	Значение по умолчанию	Description
`LogLevel`	`OFF`	Уровень ведения журнала, который является значением 0–6: — 0. Отключите все ведение журнала. — 1. Включение ведения журнала на уровне FATAL, которое регистрирует очень серьезные события ошибок, что приведет к прерыванию соединителя. — 2. Включение ведения журнала на уровне ERROR, которое регистрирует события ошибок, которые по-прежнему могут позволить соединителю продолжать работу. — 3. Включение ведения журнала на уровне ПРЕДУПРЕЖДЕНИЯ, которое регистрирует события, которые могут привести к ошибке, если действие не предприняно. — 4. Включение ведения журнала на уровне INFO, которое записывает общие сведения, описывающие ход выполнения соединителя. — 5. Включение ведения журнала на уровне ОТЛАДКИ, которое записывает подробные сведения, полезные для отладки соединителя. — 6. Включение ведения журнала на уровне TRACE, которое регистрирует все действия соединителя. Используйте это свойство, чтобы включить или отключить ведение журнала в соединителе и указать объем сведений, включенных в файлы журнала.
`LogPath`	Чтобы определить путь по умолчанию для журналов, драйвер использует набор значений для этих системных свойств в этом порядке приоритета: 1. `user.dir` 2. `java.io.tmpdir` 3. Текущий каталог, другими словами `.`	Полный путь к папке, в которой соединитель сохраняет файлы журналов при включении ведения журнала, в форме строки. Чтобы убедиться, что URL-адрес подключения совместим со всеми приложениями JDBC, избежать обратной косой черты (`\`) в пути к файлу, введя другую обратную косую черту. `LogPath` Если значение недопустимо, соединитель отправляет записанные данные в стандартный выходной поток (System.out).
`LogFileSize`	Нет максимального значения	Максимальный допустимый размер файла журнала, указанный в МБ
`LogFileCount`	Нет максимального значения	Максимальное количество разрешенных файлов журнала

Включение и настройка ведения журнала

Драйвер JDBC поддерживает платформы Java (SLF4J) и java.util.logging (JUL). Драйвер использует платформу ведения журнала JUL по умолчанию.

Чтобы включить и настроить ведение журнала для драйвера JDBC, выполните следующие действия.

Включите платформу ведения журнала, которую вы хотите использовать:
- Для ведения журнала SLF4J задайте системное свойство -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER и укажите реализацию привязки SLF4J (совместимую с SLF4J версии 2.0.13 и выше) и соответствующим файлом конфигурации в пути класса.
- Для логирования JUL установите системное свойство -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Это значение по умолчанию.
Задайте свойство LogLevel в строке подключения требуемому уровню информации для включения в файлы журнала.
Задайте для свойства LogPath в строке подключения полный путь к папке, в которой требуется сохранить файлы журналов.

Например, следующий URL-адрес подключения включает уровень ведения журнала 6 и сохраняет файлы журналов в папку C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Перезапустите приложение JDBC и снова подключитесь к серверу, чтобы применить параметры.

Пример. Выполнение запроса с помощью драйвера JDBC

В следующем примере показано, как использовать драйвер JDBC для выполнения запроса SQL Databricks с помощью вычислительного ресурса Azure Databricks.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Поделиться через