Databricks JDBC Driver (OSS)

Статья
09/20/2024

Внимание

Этот драйвер находится в общедоступной предварительной версии и еще не доступен как открытый код.

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.

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

Драйвер JDBC (OSS) Databricks публикуется в репозитории Maven. Последняя версия — 0.9.1-oss.

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

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

Выполните вход в рабочую область 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 (OSS) Databricks поддерживает секреты OAuth Azure Для проверки подлинности учетных данных клиента 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`, , `ProxyHostProxyPortProxyPwd`и ).`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_photo`	`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`	`4`	Уровень ведения журнала, который является значением 0–6: — 0. Отключите все ведение журнала. — 1. Включение ведения журнала на уровне FATAL, которое регистрирует очень серьезные события ошибок, что приведет к прерыванию соединителя. — 2. Включение ведения журнала на уровне ERROR, которое регистрирует события ошибок, которые по-прежнему могут позволить соединителю продолжать работу. — 3. Включение ведения журнала на уровне ПРЕДУПРЕЖДЕНИЯ, которое регистрирует события, которые могут привести к ошибке, если действие не предприняно. — 4. Включение ведения журнала на уровне INFO, которое записывает общие сведения, описывающие ход выполнения соединителя. — 5. Включение ведения журнала на уровне ОТЛАДКИ, которое записывает подробные сведения, полезные для отладки соединителя. — 6. Включение ведения журнала на уровне TRACE, которое регистрирует все действия соединителя. Используйте это свойство, чтобы включить или отключить ведение журнала в соединителе и указать объем сведений, включенных в файлы журнала.
`LogPath`	`logs/application.log`	Полный путь к папке, в которой соединитель сохраняет файлы журналов при включении ведения журнала в виде строки. `LogPath` Если значение недопустимо, соединитель отправляет записанные данные в стандартный выходной поток (System.out).

Пример. Выполнение запроса с помощью драйвера 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();
        }
    }
}

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