Driver Databricks JDBC (OSS)

Artikel
09/26/2024

Penting

Driver ini dalam Pratinjau Umum dan belum tersedia sebagai sumber terbuka.

Databricks menyediakan driver JDBC perangkat lunak sumber terbuka (OSS) yang memungkinkan Anda menghubungkan alat seperti DataGrip, DBeaver, dan SQL Workbench/J ke Azure Databricks melalui Java Database Connectivity (JDBC), spesifikasi standar industri untuk mengakses sistem manajemen database.

Driver ini telah menerapkan API JDBC dan menyediakan fungsionalitas inti termasuk OAuth, Cloud Fetch, dan fitur seperti penyerapan volume Unity Catalog. Ini menjalankan mode kueri asli dan mendukung kueri berparameter asli, dan dapat berjalan menggunakan API Eksekusi Pernyataan, yang menyediakan fitur retensi hasil kueri yang bermanfaat, atau Thrift.

Artikel ini menyediakan informasi tentang menginstal dan menggunakan Driver JDBC Databricks (OSS). Untuk informasi tentang Driver JDBC Non-OSS Databricks lihat Driver Databricks JDBC.

Persyaratan

Untuk menggunakan Driver Databricks JDBC (OSS), persyaratan berikut harus dipenuhi:

Java Runtime Environment (JRE) 11.0 atau lebih tinggi. Pengujian CI didukung pada JRE 11, 17, dan 21.

Pasang driver

Driver Databricks JDBC (OSS) diterbitkan di Repositori Maven. Versi terbarunya adalah 0.9.1-oss.

Untuk menginstal driver, Anda dapat melakukan salah satu hal berikut:

Untuk proyek Maven, tambahkan dependensi berikut ke file proyek pom.xml untuk menginstruksikan Maven mengunduh driver JDBC secara otomatis dengan versi yang ditentukan:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.1-oss</version>
  <scope>runtime</scope>
</dependency>
```
Untuk proyek Gradle, tambahkan dependensi berikut ke file build proyek untuk menginstruksikan Gradle mengunduh driver JDBC secara otomatis dengan versi yang ditentukan:
```
implementation 'com.databricks:databricks-jdbc:0.9.1-oss'
```

Untuk melihat sintaks dependensi untuk jenis proyek lain, dan untuk mendapatkan nomor versi terbaru Dari Driver JDBC Databricks (OSS), lihat Repositori Maven.

Mengonfigurasi URL koneksi

Untuk menyambungkan ke ruang kerja Azure Databricks menggunakan driver JDBC, Anda perlu menentukan URL koneksi JDBC yang menyertakan berbagai pengaturan koneksi seperti nama host server ruang kerja Azure Databricks Anda, pengaturan sumber daya komputasi, dan kredensial autentikasi untuk menyambungkan ke ruang kerja.

Anda dapat mengatur nilai properti ini pada URL koneksi JDBC, mengatur dan meneruskannya ke metode DriverManager.getConnection, atau kombinasi keduanya. Lihat dokumentasi penyedia tentang cara terbaik untuk terhubung menggunakan aplikasi, klien, SDK, API, atau alat SQL spesifik Anda.

URL koneksi JDBC harus dalam format berikut. Properti tidak peka huruf besar/kecil.

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

Atau, tentukan pengaturan menggunakan java.util.Properties kelas atau kombinasi:

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

Elemen URL koneksi dijelaskan dalam tabel berikut. Untuk informasi tentang properti tambahan, termasuk properti autentikasi, lihat bagian di bawah ini. Elemen dan properti URL tidak peka huruf besar/kecil.

Elemen atau properti URL	Deskripsi
`<server-hostname>`	Nilai nama host server sumber daya komputasi Azure Databricks.
`<port>`	Nilai port sumber daya komputasi Azure Databricks. Nilai defaultnya adalah `443`.
`<schema>`	Nama skema. Atau Anda dapat mengatur `ConnSchema` properti . Lihat Properti koneksi.
`httpPath`	Nilai jalur HTTP sumber daya komputasi Azure Databricks. Konektor membentuk alamat HTTP untuk disambungkan dengan menambahkan `httpPath` nilai ke host dan port yang ditentukan dalam URL koneksi. Misalnya, untuk menyambungkan ke alamat `http://localhost:10002/cliservice`HTTP , Anda akan menggunakan URL koneksi berikut: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Untuk mendapatkan URL koneksi JDBC untuk kluster Azure Databricks:

Masuk ke ruang kerja Azure Databricks Anda.
Di bar samping, klik Komputasi, lalu klik nama kluster target.
Pada tab Konfigurasi , perluas opsi Tingkat Lanjut.
Klik tab JDBC/ODBC .
Salin URL JDBC untuk digunakan sebagai URL koneksi JDBC, atau buat URL dari nilai di bidang Nama host Server, Port, dan Jalur HTTP.

Untuk mendapatkan URL koneksi JDBC untuk gudang Databricks SQL:

Masuk ke ruang kerja Azure Databricks Anda.
Di bar samping, klik Gudang SQL, lalu klik nama gudang target.
Klik tab Detail koneksi.
Salin URL JDBC untuk digunakan sebagai URL koneksi JDBC, atau buat URL dari nilai di bidang Nama host Server, Port, dan Jalur HTTP.

Mengautentikasi driver

Anda dapat mengautentikasi koneksi driver JDBC menggunakan salah satu mekanisme autentikasi berikut:

Autentikasi pengguna-ke-mesin (U2M) OAuth (Disarankan)
Autentikasi mesin-ke-mesin (M2M) OAuth
Token akses pribadi Azure Databricks

Autentikasi pengguna ke komputer (U2M) OAuth

Driver JDBC mendukung autentikasi pengguna-ke-mesin (U2M) OAuth untuk masuk dan menyetujui manusia secara real time untuk mengautentikasi akun pengguna Databricks target. Ini juga dikenal sebagai autentikasi OAuth berbasis browser.

Azure Databricks telah membuat ID databricks-sql-jdbc klien OAuth untuk pelanggan. Ini juga merupakan ID klien OAuth default yang digunakan dalam driver JDBC. Untuk mengonfigurasi autentikasi OAuth U2M, cukup tambahkan properti berikut ke URL atau java.util.Properties objek koneksi JDBC yang sudah ada:

Properti	Nilai
`AuthMech`	`11`
`Auth_Flow`	`2`

Autentikasi mesin-ke-mesin (M2M) OAuth

Driver JDBC mendukung autentikasi mesin-ke-mesin (M2M) OAuth menggunakan perwakilan layanan Azure Databricks. Ini juga dikenal sebagai autentikasi kredensial klien OAuth 2.0. Lihat Mengautentikasi akses ke Azure Databricks dengan perwakilan layanan menggunakan OAuth (OAuth M2M).

Untuk mengonfigurasi autentikasi kredensial klien OAuth M2M atau OAuth 2.0:

Buat perwakilan layanan terkelola ID Microsoft Entra lalu tetapkan ke akun dan ruang kerja Azure Databricks. Untuk detailnya, lihat Mengelola perwakilan layanan.

Penting

Driver Databricks JDBC (OSS) mendukung rahasia OAuth Azure Databricks untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0. Rahasia ID Microsoft Entra tidak didukung.
Buat rahasia OAuth Azure Databricks untuk perwakilan layanan. Untuk melakukan ini, lihat Membuat dan menggunakan token akses secara manual untuk autentikasi M2M OAuth.
Berikan akses perwakilan layanan ke kluster atau gudang Anda. Lihat Izin komputasi atau Mengelola gudang SQL.

Tambahkan properti berikut ke URL atau java.util.Properties objek koneksi JDBC yang sudah ada:

Properti	Nilai
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Nilai ID Aplikasi (klien) perwakilan layanan.
`OAuth2Secret`	Rahasia Azure Databricks OAuth perwakilan layanan. (Rahasia ID Microsoft Entra tidak didukung untuk autentikasi kredensial klien OAuth M2M atau OAuth 2.0.)

Token akses pribadi Azure Databricks

Untuk mengautentikasi koneksi driver JDBC Anda menggunakan token akses pribadi Azure Databricks, tambahkan properti berikut ke URL atau java.util.Properties objek koneksi JDBC Anda:

Properti	Nilai
`AuthMech`	`3`
`user`	Nilai `token`, sebagai string.
`PWD` atau `password`	Nilai token akses pribadi Azure Databricks Anda, sebagai string.

Properti koneksi

Properti koneksi tambahan berikut didukung oleh driver JDBC. Properti tidak peka huruf besar/kecil.

Properti	Nilai default	Deskripsi
`AuthMech`	Wajib diisi	Mekanisme autentikasi, di mana `3` menentukan mekanisme adalah token akses pribadi Azure Databricks, dan `11` menentukan mekanismenya adalah token OAuth 2.0. Properti tambahan diperlukan untuk setiap mekanisme. Lihat Mengautentikasi driver.
`Auth_Flow`	`0`	Alur autentikasi OAuth2 untuk koneksi driver. Properti ini diperlukan jika `AuthMech` adalah `11`.
`SSL`	`1`	Apakah konektor berkomunikasi dengan server Spark melalui soket yang diaktifkan SSL.
`ConnCatalog` atau `catalog`	`SPARK`	Nama katalog default yang akan digunakan.
`ConnSchema` atau `schema`	`default`	Nama skema default yang akan digunakan. Ini dapat ditentukan baik dengan mengganti `<schema>` di URL dengan nama skema yang akan digunakan atau dengan mengatur `ConnSchema` properti ke nama skema yang akan digunakan.
`ProxyAuth`	`0`	Jika diatur ke `1`, driver menggunakan pengguna dan kata sandi autentikasi proksi, yang diwakili oleh `ProxyUID` dan `ProxyPwd`.
`ProxyHost`	`null`	String yang mewakili nama host proksi yang akan digunakan ketika `UseProxy` juga diatur ke `1`.
`ProxyPort`	`null`	Bilangan bulat yang mewakili jumlah port proksi yang akan digunakan ketika `UseProxy` juga diatur ke `1`.
`ProxyUID`	`null`	String yang mewakili nama pengguna yang akan digunakan untuk autentikasi proksi saat `ProxyAuth` dan `UseProxy` juga diatur ke `1`.
`ProxyPwd`	`null`	String yang mewakili kata sandi yang akan digunakan untuk autentikasi proksi saat `ProxyAuth` dan `UseProxy` juga diatur ke `1`.
`UseProxy`	`0`	Jika diatur ke `1`, driver menggunakan pengaturan proksi yang disediakan (misalnya: `ProxyAuth`, , `ProxyHost`, `ProxyPortProxyPwd`, dan `ProxyUID`).
`UseSystemProxy`	`0`	Jika diatur ke `1`, driver menggunakan pengaturan proksi yang telah diatur pada tingkat sistem. Jika ada properti proksi tambahan yang diatur dalam URL koneksi, properti proksi tambahan ini mengambil alih properti yang telah ditetapkan di tingkat sistem.
`UseCFProxy`	`0`	Jika diatur ke `1`, driver menggunakan pengaturan proksi pengambilan cloud jika disediakan, jika tidak, gunakan proksi reguler.
`CFProxyAuth`	`0`	Jika diatur ke `1`, driver menggunakan pengguna dan kata sandi autentikasi proksi, yang diwakili oleh `CFProxyUID` dan `CFProxyPwd`.
`CFProxyHost`	`null`	String yang mewakili nama host proksi yang akan digunakan ketika `UseCFProxy` juga diatur ke `1`.
`CFProxyPort`	`null`	Bilangan bulat yang mewakili jumlah port proksi yang akan digunakan ketika `UseCFProxy` juga diatur ke `1`.
`CFProxyUID`	`null`	String yang mewakili nama pengguna yang akan digunakan untuk autentikasi proksi saat `CFProxyAuth` dan `UseCFProxy` juga diatur ke `1`.
`CFProxyPwd`	`null`	String yang mewakili kata sandi yang akan digunakan untuk autentikasi proksi saat `CFProxyAuth` dan `UseCFProxy` juga diatur ke `1`.
`AsyncExecPollInterval`	`200`	Waktu dalam milidetik antara setiap polling untuk status eksekusi kueri asinkron. Asinkron mengacu pada fakta bahwa panggilan RPC yang digunakan untuk menjalankan kueri terhadap Spark tidak sinkron. Ini tidak berarti bahwa operasi asinkron JDBC didukung.
`UserAgentEntry`	`browser`	Entri User-Agent yang akan disertakan dalam permintaan HTTP. Nilai ini dalam format berikut: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Apakah driver JDBC harus menggunakan klien Thrift untuk terhubung ke kluster serba guna. Nilai default berfungsi untuk gudang SQL.

Properti konfigurasi SQL

Properti konfigurasi SQL berikut didukung oleh driver JDBC. Ini juga dijelaskan dalam parameter Konfigurasi. Properti tidak peka huruf besar/kecil.

Properti	Nilai default	Deskripsi
`ansi_mode`	`TRUE`	Apakah akan mengaktifkan perilaku ANSI SQL yang ketat untuk fungsi dan aturan transmisi tertentu.
`enable_photo`	`TRUE`	Apakah akan mengaktifkan mesin kueri vektor Photon.
`legacy_time_parser_policy`	`EXCEPTION`	Metode yang digunakan untuk mengurai dan memformat tanggal dan tanda waktu. Nilai yang valid adalah `EXCEPTION`, `LEGACY`, dan `CORRECTED`.
`max_file_partition_bytes`	`128m`	Jumlah maksimum byte untuk dikemas ke dalam partisi tunggal saat membaca dari sumber berbasis file. Pengaturan dapat berupa bilangan bulat positif dan secara opsional menyertakan ukuran seperti `b` (byte), `k` atau `kb` (1024 byte).
`read_only_external_metastore`	`false`	Mengontrol apakah metastore eksternal diperlakukan sebagai baca-saja.
`statement_timeout`	`172800`	Mengatur batas waktu pernyataan SQL antara 0 dan 172800 detik.
`timezone`	`UTC`	Atur zona waktu lokal. ID wilayah dalam formulir `area/city`, seperti Amerika/Los_Angeles atau offset zona dalam format (+\|-)HH, (+\|-)HH:mm atau (+\|-)HH:mm:ss, misalnya -08, +01:00 atau -13:33:33. Selain itu, `UTC` didukung sebagai alias untuk +00:00
`use_cached_result`	`true`	Apakah Databricks SQL menyimpan cache dan menggunakan kembali hasil jika memungkinkan.

Properti logging

Properti pengelogan berikut didukung oleh driver JDBC. Properti tidak peka huruf besar/kecil.

Properti	Nilai default	Deskripsi
`LogLevel`	`4`	Tingkat pengelogan, yang merupakan nilai 0 hingga 6: - 0: Nonaktifkan semua pengelogan. - 1: Aktifkan pengelogan pada tingkat FATAL, yang mencatat peristiwa kesalahan yang sangat parah yang akan menyebabkan konektor dibatalkan. - 2: Aktifkan pengelogan pada tingkat KESALAHAN, yang mencatat peristiwa kesalahan yang mungkin masih memungkinkan konektor untuk terus berjalan. - 3: Aktifkan pengelogan pada tingkat PERINGATAN, yang mencatat peristiwa yang mungkin mengakibatkan kesalahan jika tindakan tidak diambil. - 4: Aktifkan pengelogan pada tingkat INFO, yang mencatat informasi umum yang menjelaskan kemajuan konektor. - 5: Aktifkan pengelogan pada tingkat DEBUG, yang mencatat informasi terperinci yang berguna untuk men-debug konektor. - 6: Aktifkan pengelogan pada tingkat TRACE, yang mencatat semua aktivitas konektor. Gunakan properti ini untuk mengaktifkan atau menonaktifkan pengelogan di konektor dan untuk menentukan jumlah detail yang disertakan dalam file log.
`LogPath`	`logs/application.log`	Jalur lengkap ke folder tempat konektor menyimpan file log saat pengelogan diaktifkan, sebagai string. `LogPath` Jika nilai tidak valid, konektor mengirimkan informasi yang dicatat ke aliran output standar (System.out).

Contoh: Menjalankan kueri menggunakan driver JDBC

Contoh berikut menunjukkan cara menggunakan driver JDBC untuk menjalankan kueri Databricks SQL menggunakan sumber daya komputasi 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();
        }
    }
}

Bagikan melalui