Sterownik JDBC usługi Databricks (OSS)

Artykuł
01/23/2025

Ważne

Ten sterownik znajduje się w publicznej wersji zapoznawczej i będzie dostępny jako open source, gdy stanie się ogólnie dostępny (GA).

Usługa Databricks JDBC (OSS), najnowsza wersja sterownika, umożliwia łączenie narzędzi, takich jak DataGrip, DBeaveri SQL Workbench/J do usługi Azure Databricks za pośrednictwem usługi Java Database Connectivity (JDBC), standardowej specyfikacji branżowej na potrzeby uzyskiwania dostępu do systemów zarządzania bazami danych.

Ten sterownik zaimplementował interfejsy API JDBC i zapewnia podstawowe funkcje, w tym OAuth, Cloud Fetch oraz takie funkcje jak ingestia woluminów w Unity Catalog. Uruchamia natywny tryb zapytania i obsługuje natywne zapytanie sparametryzowane i może działać przy użyciu interfejsów API wykonywania instrukcji, które udostępnia funkcję przechowywania wyników korzystnego zapytania lub Thrift.

Ten artykuł zawiera informacje na temat instalowania i używania sterownika JDBC usługi Databricks (OSS). Aby uzyskać informacje o sterowniku JDBC usługi Databricks innego niż OSS, zobacz Sterownik JDBC usługi Databricks.

Wymagania

Aby użyć sterownika JDBC usługi Databricks (OSS), należy spełnić następujące wymagania:

Środowisko uruchomieniowe Java (JRE) w wersji 11.0 lub nowszej. Testowanie ciągłej integracji jest obsługiwane w środowiskach JRE 11, 17 i 21.

Uwaga

W wyniku zmiany zestawu JDK 16, która spowodowała problem ze zgodnością z biblioteką Apache Arrow używaną przez sterownik JDBC, błędy środowiska uruchomieniowego mogą wystąpić podczas korzystania ze sterownika JDBC z zestawem JDK 16 lub nowszym. Aby zapobiec tym błędom, uruchom ponownie aplikację lub sterownik przy użyciu następującej opcji polecenia JVM:

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

Instalowanie sterownika

Sterownik JDBC usługi Databricks (OSS) jest publikowany w repozytorium Maven.

Aby zainstalować sterownik, możesz wykonać dowolną z następujących czynności:

W przypadku projektów Maven dodaj następującą zależność do pliku projektu pom.xml , aby poinstruować narzędzie Maven, aby automatycznie pobrać sterownik JDBC z określoną wersją:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
W przypadku projektów Gradle dodaj następującą zależność do pliku kompilacji projektu, aby poinstruować narzędzie Gradle o automatycznym pobraniu sterownika JDBC z określoną wersją:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Aby wyświetlić składnię zależności dla innych typów projektów oraz aby uzyskać najnowszą wersję sterownika JDBC usługi Databricks (OSS), zobacz Repozytorium Maven.

Konfigurowanie adresu URL połączenia

Aby nawiązać połączenie z obszarem roboczym usługi Azure Databricks przy użyciu sterownika JDBC, należy określić adres URL połączenia JDBC zawierający różne ustawienia połączenia, takie jak nazwa hosta serwera obszaru roboczego usługi Azure Databricks, ustawienia zasobów obliczeniowych i poświadczenia uwierzytelniania, aby nawiązać połączenie z obszarem roboczym.

Można ustawić wartość tych właściwości w adresie URL połączenia JDBC, ustawić i przekazać je do metody DriverManager.getConnectionlub kombinacji obu tych elementów. Zapoznaj się z dokumentacją dostawcy, aby dowiedzieć się, jak najlepiej nawiązać połączenie przy użyciu określonej aplikacji, klienta, zestawu SDK, interfejsu API lub narzędzia SQL.

Adres URL połączenia JDBC musi mieć następujący format. Właściwości są niewrażliwe na wielkość liter.

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

Alternatywnie określ ustawienia przy użyciu java.util.Properties klasy lub kombinacji:

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");

Elementy adresu URL połączenia zostały opisane w poniższej tabeli. Aby uzyskać informacje o dodatkowych właściwościach, w tym właściwościach uwierzytelniania, zobacz poniższe sekcje. Elementy i właściwości adresu URL są niewrażliwe na wielkość liter.

Element lub właściwość adresu URL	opis
`<server-hostname>`	Wartość nazwy hosta serwera zasobu obliczeniowego usługi Azure Databricks.
`<port>`	Wartość portu zasobu obliczeniowego usługi Azure Databricks. Domyślna wartość to `443`.
`<schema>`	Nazwa schematu. Alternatywnie można ustawić właściwość `ConnSchema`. Zobacz Właściwości połączenia.
`httpPath`	Wartość ścieżki HTTP zasobu obliczeniowego usługi Azure Databricks. Łącznik tworzy adres HTTP, z którym ma nawiązać połączenie, dołączając `httpPath` wartość do hosta i portu określonego w adresie URL połączenia. Aby na przykład nawiązać połączenie z adresem `http://localhost:10002/cliservice`HTTP, użyj następującego adresu URL połączenia: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Aby uzyskać adres URL połączenia JDBC dla klastra usługi Azure Databricks :

Zaloguj się do obszaru roboczego usługi Azure Databricks.
Na pasku bocznym kliknij pozycję Obliczenia, a następnie kliknij nazwę klastra docelowego.
Na karcie Konfiguracja rozwiń pozycję Opcje zaawansowane.
Kliknij kartę JDBC/ODBC .
Skopiuj adres URL JDBC do użycia jako adres URL połączenia JDBC lub skonstruuj adres URL z wartości w polach Nazwa hosta serwera, Porti ścieżka HTTP.

Aby uzyskać adres URL połączenia JDBC dla usługi Databricks SQL Warehouse:

Zaloguj się do obszaru roboczego usługi Azure Databricks.
Na pasku bocznym kliknij pozycję SQL Warehouses, a następnie kliknij nazwę magazynu docelowego.
Kliknij kartę Szczegóły połączenia.
Skopiuj adres URL JDBC do użycia jako adres URL połączenia JDBC lub skonstruuj adres URL z wartości w polach Nazwa hosta serwera, Porti ścieżka HTTP.

Uwierzytelnianie sterownika

Połączenie sterownika JDBC można uwierzytelnić przy użyciu jednego z następujących mechanizmów uwierzytelniania:

Uwierzytelnianie od użytkownika do komputera (U2M) OAuth (zalecane)
Uwierzytelnianie OAuth między maszynami (M2M)
Osobisty token dostępu usługi Azure Databricks

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Sterownik JDBC obsługuje uwierzytelnianie użytkownika do komputera OAuth (U2M) na potrzeby logowania użytkownika w czasie rzeczywistym i zgody na uwierzytelnianie docelowego konta użytkownika usługi Databricks. Jest to również nazywane uwierzytelnianiem OAuth opartym na przeglądarce.

Usługa Azure Databricks utworzyła identyfikator databricks-sql-jdbc klienta OAuth dla klientów. Jest to również domyślny identyfikator klienta OAuth używany w sterowniku JDBC. Aby skonfigurować uwierzytelnianie OAuth U2M, wystarczy dodać następujące właściwości do istniejącego adresu URL java.util.Properties lub obiektu połączenia JDBC:

Właściwości	Wartość
`AuthMech`	`11`
`Auth_Flow`	`2`

Uwierzytelnianie maszyny do maszyny OAuth (M2M)

Sterownik JDBC obsługuje uwierzytelnianie maszyny do maszyny OAuth (M2M) przy użyciu jednostki usługi Azure Databricks. Jest to również znane jako uwierzytelnianie za pomocą poświadczeń klienta OAuth 2.0 . Zobacz Autoryzowanie nienadzorowanego dostępu do zasobów usługi Azure Databricks przy użyciu głównej jednostki usługi z wykorzystaniem protokołu OAuth.

Aby skonfigurować uwierzytelnianie poświadczeń klienta OAuth M2M lub OAuth 2.0:

Utwórz jednostkę usługi zarządzanej microsoft Entra ID, a następnie przypisz ją do kont i obszarów roboczych usługi Azure Databricks. Aby uzyskać szczegółowe informacje, zobacz Zarządzanie jednostkami usługi.

Ważne

Sterownik JDBC (OSS) usługi Databricks obsługuje tajne klucze OAuth usługi Azure Databricks do uwierzytelniania OAuth M2M (machine-to-machine) lub OAuth 2.0 za pomocą poświadczeń klienta. Wpisy tajne identyfikatora Entra firmy Microsoft nie są obsługiwane.
Utwórz wpis tajny OAuth usługi Azure Databricks dla jednostki usługi. Aby to zrobić, przejdź do sekcji Ręczne generowanie i użycie tokenów dostępu do uwierzytelniania jednostki usługi OAuth.
Nadaj jednostce usługi dostęp do klastra lub magazynu. Zobacz Uprawnienia obliczeniowe lub Zarządzanie usługą SQL Warehouse.

Dodaj następujące właściwości do istniejącego adresu URL java.util.Properties lub obiektu połączenia JDBC:

Właściwości	Wartość
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Wartość identyfikatora aplikacji (klienta) jednostki usługi.
`OAuth2Secret`	Wpis tajny OAuth jednostki usługi Azure Databricks. (Wpisy tajne identyfikatora entra firmy Microsoft nie są obsługiwane w przypadku uwierzytelniania OAuth M2M lub OAuth 2.0 poświadczeń klienta).

Osobisty token dostępu usługi Azure Databricks

Aby uwierzytelnić połączenie sterownika JDBC przy użyciu osobistego tokenu dostępu usługi Azure Databricks, dodaj następujące właściwości do adresu URL java.util.Properties lub obiektu połączenia JDBC:

Właściwości	Wartość
`AuthMech`	`3`
`user`	Wartość `token`, jako ciąg.
`PWD` lub `password`	Wartość osobistego tokenu dostępu usługi Azure Databricks jako ciąg.

Connection properties (Właściwości połączenia)

Następujące dodatkowe właściwości połączenia są obsługiwane przez sterownik JDBC. Właściwości są niewrażliwe na wielkość liter.

Właściwości	Wartość domyślna	opis
`AuthMech`	Wymagania	Mechanizm uwierzytelniania, w którym `3` określa mechanizm jest osobistym tokenem dostępu usługi Azure Databricks, a `11` określa mechanizm tokenów OAuth 2.0. Dodatkowe właściwości są wymagane dla każdego mechanizmu. Zobacz Uwierzytelnianie sterownika.
`Auth_Flow`	`0`	Przepływ uwierzytelniania OAuth2 dla połączenia sterownika. Ta właściwość jest wymagana, jeśli `AuthMech` jest to `11`.
`SSL`	`1`	Czy łącznik komunikuje się z serwerem Spark za pośrednictwem gniazda z obsługą protokołu SSL.
`ConnCatalog` lub `catalog`	`SPARK`	Nazwa domyślnego wykazu do użycia.
`ConnSchema` lub `schema`	`default`	Nazwa domyślnego schematu do użycia. Można to określić, zastępując `<schema>` w adresie URL nazwą schematu do użycia lub ustawiając właściwość `ConnSchema` na nazwę schematu do użycia.
`ProxyAuth`	`0`	Jeśli ustawiono wartość `1`, sterownik używa użytkownika i hasła uwierzytelniania serwera proxy reprezentowanego przez `ProxyUID` i `ProxyPwd`.
`ProxyHost`	`null`	Ciąg reprezentujący nazwę hosta serwera proxy, który ma być używany, gdy `UseProxy` jest również ustawiony na wartość `1`.
`ProxyPort`	`null`	Liczba całkowita reprezentująca liczbę portów serwera proxy do użycia, gdy `UseProxy` jest również ustawiona na wartość `1`.
`ProxyUID`	`null`	Ciąg reprezentujący nazwę użytkownika do użycia na potrzeby uwierzytelniania serwera proxy, gdy `ProxyAuth` i `UseProxy` są również ustawione na wartość `1`.
`ProxyPwd`	`null`	Ciąg znaków stanowiący hasło używane przy uwierzytelnianiu serwera proxy, gdy `ProxyAuth` i `UseProxy` są również ustawione na `1`.
`UseProxy`	`0`	Jeśli ustawiono wartość `1`, sterownik używa podanych ustawień serwera proxy (na przykład: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`i `ProxyUID`).
`UseSystemProxy`	`0`	Jeśli ustawiono wartość `1`, sterownik używa ustawień serwera proxy ustawionych na poziomie systemu. Jeśli jakiekolwiek dodatkowe właściwości serwera proxy są ustawione w adresie URL połączenia, te dodatkowe właściwości serwera proxy zastępują te, które zostały ustawione na poziomie systemu.
`UseCFProxy`	`0`	Jeśli ustawiono wartość `1`, sterownik używa ustawień serwera proxy pobierania w chmurze, jeśli zostały podane, w przeciwnym razie używane są zwykłe ustawienia serwera proxy.
`CFProxyAuth`	`0`	Jeśli ustawiono wartość `1`, sterownik używa użytkownika i hasła uwierzytelniania serwera proxy reprezentowanego przez `CFProxyUID` i `CFProxyPwd`.
`CFProxyHost`	`null`	Ciąg reprezentujący nazwę hosta serwera proxy, który ma być używany, gdy `UseCFProxy` jest również ustawiony na wartość `1`.
`CFProxyPort`	`null`	Liczba całkowita reprezentująca liczbę portów serwera proxy do użycia, gdy `UseCFProxy` jest również ustawiona na wartość `1`.
`CFProxyUID`	`null`	Ciąg reprezentujący nazwę użytkownika do użycia na potrzeby uwierzytelniania serwera proxy, gdy `CFProxyAuth` i `UseCFProxy` są również ustawione na wartość `1`.
`CFProxyPwd`	`null`	Ciąg znaków stanowiący hasło używane przy uwierzytelnianiu serwera proxy, gdy `CFProxyAuth` i `UseCFProxy` są również ustawione na `1`.
`AsyncExecPollInterval`	`200`	Czas w milisekundach między poszczególnymi sondami dla stanu wykonywania zapytania asynchronicznego. Asynchroniczne odnosi się do faktu, że wywołanie RPC używane do wykonywania zapytania względem platformy Spark jest asynchroniczne. Nie oznacza to, że operacje asynchroniczne JDBC są obsługiwane.
`UserAgentEntry`	`browser`	Wpis User-Agent, który ma zostać uwzględniony w żądaniu HTTP. Ta wartość ma następujący format: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Czy sterownik JDBC powinien używać klienta Thrift do nawiązywania połączenia z klastrem all-purpose. Wartość domyślna działa dla magazynów SQL.

Właściwości konfiguracji SQL

Następujące właściwości konfiguracji SQL są obsługiwane przez sterownik JDBC. Są one również opisane w Parametry konfiguracji. Właściwości są niewrażliwe na wielkość liter.

Właściwości	Wartość domyślna	opis
`ansi_mode`	`TRUE`	Czy włączyć ścisłe zachowanie ANSI SQL dla niektórych funkcji i reguł rzutowania.
`enable_photon`	`TRUE`	Czy włączyć aparat zapytań wektoryzowanych photon.
`legacy_time_parser_policy`	`EXCEPTION`	Metody używane do analizowania i formatowania dat i sygnatur czasowych. Prawidłowe wartości to `EXCEPTION`, `LEGACY`i `CORRECTED`.
`max_file_partition_bytes`	`128m`	Maksymalna liczba bajtów do spakowania w jedną partycję podczas odczytywania ze źródeł opartych na plikach. Ustawienie może być dowolną dodatnią liczbą całkowitą i opcjonalnie zawiera miarę, taką jak `b` (bajty) `k` lub `kb` (1024 bajty).
`read_only_external_metastore`	`false`	Określa, czy zewnętrzny magazyn metadanych jest traktowany jako tylko do odczytu.
`statement_timeout`	`172800`	Ustawia limit czasu instrukcji SQL z zakresu od 0 do 172800 sekund.
`timezone`	`UTC`	Ustaw lokalną strefę czasową. Identyfikatory regionów w postaci `area/city`, takie jak Ameryka/Los_Angeles lub przesunięcia strefy w formacie (+\|-)HH, (+\|-)HH:mm lub (+\|-)HH:mm:mm:ss, np. -08, +01:00 lub -13:33:33. `UTC` Ponadto jest obsługiwany jako alias dla +00:00
`use_cached_result`	`true`	Czy usługa Databricks SQL buforuje i ponownie używa wyników, gdy jest to możliwe.

Właściwości rejestrowania

Następujące właściwości rejestrowania są obsługiwane przez sterownik JDBC. Właściwości są niewrażliwe na wielkość liter.

Właściwości	Wartość domyślna	opis
`LogLevel`	`OFF`	Poziom rejestrowania, czyli wartość od 0 do 6: - 0: Wyłącz wszystkie rejestrowanie. - 1: Włącz rejestrowanie na poziomie KRYTYCZNYm, który rejestruje bardzo poważne zdarzenia błędów, które spowodują przerwanie łącznika. - 2: Włącz rejestrowanie na poziomie BŁĘDU, który rejestruje zdarzenia błędów, które mogą nadal zezwalać łącznikowi na kontynuowanie działania. - 3: Włącz rejestrowanie na poziomie OSTRZEŻENIA, które rejestruje zdarzenia, które mogą spowodować błąd, jeśli nie zostanie podjęta akcja. - 4: Włącz rejestrowanie na poziomie INFO, który rejestruje ogólne informacje opisujące postęp łącznika. - 5: Włącz rejestrowanie na poziomie DEBUG, który rejestruje szczegółowe informacje przydatne do debugowania łącznika. - 6: Włącz rejestrowanie na poziomie TRACE, który rejestruje wszystkie działania łącznika. Użyj tej właściwości, aby włączyć lub wyłączyć rejestrowanie w łączniku i określić ilość szczegółów zawartych w plikach dziennika.
`LogPath`	Aby określić domyślną ścieżkę dzienników, sterownik używa wartości ustawionej dla tych właściwości systemowych w następującej kolejności priorytetu: 1. `user.dir` 2. `java.io.tmpdir` 3. bieżący katalog, innymi słowy `.`	Pełna ścieżka do folderu, w którym łącznik zapisuje pliki dziennika, gdy rejestrowanie jest włączone, jako ciąg znaków. Aby upewnić się, że adres URL połączenia jest zgodny ze wszystkimi aplikacjami JDBC, należy usunąć ukośniki odwrotne (`\`) w ścieżce pliku, wpisując kolejny ukośnik odwrotny. Jeśli wartość jest nieprawidłowa `LogPath` , łącznik wysyła zarejestrowane informacje do standardowego strumienia wyjściowego (System.out).
`LogFileSize`	Brak maksymalnej wartości	Maksymalny dozwolony rozmiar pliku dziennika określony w MB
`LogFileCount`	Brak maksymalnej wartości	Maksymalna liczba dozwolonych plików dziennika

Włączanie i konfigurowanie rejestrowania

Sterownik JDBC obsługuje struktury Simple Logging Unique for Java (SLF4J) i java.util.logging (JUL). Sterownik domyślnie używa struktury rejestrowania JUL.

Aby włączyć i skonfigurować rejestrowanie sterownika JDBC:

Włącz strukturę rejestrowania, której chcesz użyć:
- W przypadku rejestrowania SLF4J ustaw właściwość systemową -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER oraz dostarcz implementację powiązania SLF4J (zgodną z wersją SLF4J w wersji 2.0.13 lub nowszej), wraz z odpowiadającym plikiem konfiguracji w ścieżce klasy.
- W przypadku rejestrowania JUL ustaw właściwość systemu -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Jest to opcja domyślna.
Ustaw właściwość LogLevel w parametrach połączenia na żądany poziom informacji do uwzględnienia w plikach dziennika.
Ustaw właściwość LogPath w parametrze połączenia na pełną ścieżkę do folderu, w którym chcesz zapisać pliki logów.

Na przykład następujący adres URL połączenia umożliwia rejestrowanie na poziomie 6 i zapisuje pliki dziennika w folderze C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Uruchom ponownie aplikację JDBC i ponownie nawiąż połączenie z serwerem, aby zastosować ustawienia.

Przykład: uruchamianie zapytania przy użyciu sterownika JDBC

W poniższym przykładzie pokazano, jak używać sterownika JDBC do uruchamiania zapytania SQL usługi Databricks przy użyciu zasobu obliczeniowego usługi 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();
        }
    }
}

Udostępnij za pośrednictwem