Koneksi JDBC

Nota

Fitur ini adalah beta tingkat ruang kerja pada Databricks Runtime 17.3 ke atas. Untuk mengaktifkan fitur ini di ruang kerja Anda, lihat Mengelola pratinjau tingkat ruang kerja.

Azure Databricks mendukung menyambungkan ke database eksternal menggunakan JDBC. Anda dapat menggunakan koneksi JDBC Unity Catalog untuk membaca dan menulis ke sumber data dengan Spark Data Source API atau Azure Databricks Remote Query SQL API. Koneksi JDBC adalah objek yang dapat diamankan di Katalog Unity yang menentukan driver JDBC, jalur URL, dan kredensial untuk mengakses database eksternal. Koneksi JDBC didukung di seluruh jenis komputasi Unity Catalog, termasuk tanpa server, kluster standar, kluster khusus, dan Databricks SQL.

Manfaat menggunakan koneksi JDBC

Baca dan tulis ke sumber data menggunakan JDBC dengan Spark Data Source API.
Baca dari sumber data dengan JDBC menggunakan Remote Query SQL API.
Akses yang diatur ke sumber data menggunakan koneksi Katalog Unity.
Buat koneksi satu kali dan gunakan kembali di semua komputasi Katalog Unity.
Stabil untuk peningkatan Spark dan komputasi.
Kredensial koneksi disembunyikan dari pengguna yang melakukan pencarian.

JDBC versus federasi kueri

JDBC adalah komplementer dengan federasi kueri. Databricks merekomendasikan untuk memilih federasi kueri karena alasan berikut:

Federasi kueri menyediakan kontrol akses dan tata kelola yang rinci di tingkat tabel menggunakan katalog asing. Koneksi JDBC Unity Catalog hanya menyediakan tata kelola di tingkat koneksi.
Federasi kueri mendorong kueri Spark untuk performa kueri yang optimal.

Nota

Federasi kueri mendukung banyak database populer, termasuk Oracle, MySQL, PostgreSQL, SQL Server, dan Snowflake. Jika database Anda didukung, Databricks merekomendasikan penggunaan federasi kueri alih-alih koneksi JDBC. Lihat Federasi Lakehouse untuk daftar lengkap database yang didukung.

Namun, pilih untuk menggunakan koneksi JDBC Unity Catalog dalam skenario berikut:

Database Anda tidak didukung oleh federasi pencarian.
Anda ingin menggunakan driver JDBC tertentu.
Anda perlu menulis ke sumber data menggunakan Spark (federasi kueri tidak mendukung penulisan).
Anda memerlukan lebih banyak kontrol fleksibilitas, performa, dan paralelisasi melalui opsi Spark Data Source API.
Anda ingin mendorong kueri ke bawah dengan opsi Spark query .

Mengapa menggunakan sumber data JDBC versus PySpark?

Sumber data PySpark adalah alternatif untuk sumber data JDBC Spark.

Gunakan koneksi JDBC:

Jika Anda ingin menggunakan dukungan Spark JDBC bawaan.
Jika Anda ingin menggunakan driver JDBC siap pakai yang sudah ada.
Jika Anda memerlukan tata kelola Katalog Unity di tingkat koneksi.
Jika Anda ingin terhubung dari jenis komputasi Katalog Unity apa pun: TANPA server, standar, khusus, SQL API.
Jika Anda ingin menggunakan koneksi Anda dengan API Python, Scala, dan SQL.

Gunakan sumber data PySpark:

Jika Anda ingin memiliki fleksibilitas untuk mengembangkan dan merancang sumber data atau sink data Spark Anda menggunakan Python.
Jika Anda hanya menggunakannya di notebook atau pekerjaan berbasis PySpark.
Jika Anda ingin menerapkan logika partisi kustom.

Baik sumber data JDBC maupun PySpark tidak mendukung pushdown predikat. Mereka juga tidak mengekspos statistik ke pengoptimal kueri untuk membantu memilih urutan operasi.

Cara kerjanya

Untuk menyambungkan ke sumber data menggunakan koneksi JDBC, instal driver JDBC pada komputasi Spark. Koneksi memungkinkan Anda menentukan dan menginstal driver JDBC di kotak pasir terisolasi yang dapat diakses oleh komputasi Spark untuk memastikan keamanan Spark dan tata kelola Katalog Unity. Untuk informasi selengkapnya tentang sandboxing, lihat Bagaimana Databricks memberlakukan isolasi pengguna?.

Sebelum Anda mulai

Untuk menggunakan koneksi JDBC dengan Spark Data Source API pada kluster tanpa server dan standar, Anda harus terlebih dahulu memenuhi persyaratan berikut:

Persyaratan ruang kerja:

Ruang kerja Azure Databricks diaktifkan untuk Katalog Unity

Persyaratan komputasi:

Konektivitas jaringan dari sumber daya komputasi Anda ke sistem database target. Lihat Konektivitas jaringan.
Komputasi Azure Databricks harus menggunakan tanpa server, atau Databricks Runtime 17.3 LTS atau lebih tinggi pada mode standar atau mode akses khusus.
Gudang SQL harus pro atau tanpa server dan harus menggunakan 2025.35 atau lebih tinggi.

Izin diperlukan:

Untuk membuat koneksi, Anda harus memiliki CREATE CONNECTION hak istimewa pada metastore yang terhubung dengan ruang kerja.
CREATE atau MANAGE akses ke volume Unity Catalog oleh pencipta koneksi.
Akses volume oleh pengguna yang meminta koneksi.
Izin tambahan ditentukan di setiap bagian berbasis tugas yang mengikutinya.

Langkah 1: Buat volume dan instal JDBC JAR

Koneksi JDBC membaca dan menginstal JAR driver JDBC dari Unity Catalog volume.

Jika Anda tidak memiliki akses tulis dan baca ke volume yang sudah ada, buat volume baru:
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
Unggah driver JDBC JAR ke volume.

Berikan akses baca pada volume tersebut kepada pengguna yang meminta koneksi:

GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`

Langkah 2: Membuat koneksi JDBC

Koneksi JDBC adalah objek yang dapat diamankan di Unity Catalog yang menentukan driver JDBC, jalur URL, dan kredensial untuk mengakses sistem database eksternal dan opsi yang diizinkan untuk digunakan oleh pengguna kueri. Untuk membuat koneksi, gunakan Catalog Explorer atau CREATE CONNECTION perintah SQL di buku catatan Azure Databricks atau editor kueri Databricks SQL.

Nota

Anda juga dapat menggunakan Databricks REST API atau Databricks CLI untuk membuat koneksi. Lihat perintah POST /api/2.1/unity-catalog/connections dan perintah Unity Catalog.

Izin diperlukan: Admin atau pengguna Metastore dengan CREATE CONNECTION hak istimewa.

Eksplorer Katalog

Di ruang kerja Azure Databricks Anda, klik Katalog.
Di bagian atas panel Katalog , klik Tambahkan ikon dan pilih Buat koneksi dari menu.
Pada halaman Dasar-dasar Koneksi di wizard Menyiapkan Koneksi, masukkan nama Koneksi yang mudah dipahami.
Pilih Jenis koneksiJDBC.
(Opsional) Tambahkan komentar.
Klik Berikutnya.
Pada halaman Autentikasi , masukkan properti koneksi berikut ini:
- URL JDBC: URL koneksi JDBC untuk database Anda (misalnya, jdbc:oracle:thin:@<host>:<port>:<SID>).
- Pengguna: Nama pengguna database.
- Kata sandi: Kata sandi untuk database.
- Jalur driver JDBC: Jalur volume Katalog Unity ke JAR driver JDBC (misalnya, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
Klik Buat koneksi.

SQL

Jalankan perintah berikut ini di notebook atau editor kueri SQL, sesuaikan volume, URL, kredensial, dan externalOptionsAllowList:

DROP CONNECTION IF EXISTS <JDBC-connection-name>;

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<Schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

DESCRIBE CONNECTION <JDBC-connection-name>;

Contoh: Koneksi Oracle JDBC

Contoh berikut membuat koneksi JDBC ke database Oracle menggunakan driver tipis Oracle. Unduh JAR driver Oracle JDBC (misalnya, ojdbc11.jar) dari halaman unduhan Oracle JDBC dan unggah ke volume Katalog Unity sebelum menjalankan perintah ini.

CREATE CONNECTION oracle_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/ojdbc11.jar"]'
)
OPTIONS (
  url 'jdbc:oracle:thin:@<host>:<port>:<SID>',
  user '<oracle_user>',
  password '<oracle_password>',
  externalOptionsAllowList 'dbtable,query'
);

Pemilik atau manajer koneksi dapat menambahkan ke koneksi opsi tambahan apa pun yang didukung oleh driver JDBC.

Untuk alasan keamanan, opsi yang ditentukan dalam koneksi tidak dapat ditimpa saat menjalankan kueri. Pengguna hanya dapat menentukan opsi sumber data Spark yang belum ditentukan dalam koneksi.

externalOptionsAllowList memungkinkan pembuat koneksi untuk menentukan opsi sumber data Spark mana yang dapat disediakan pengguna pada waktu kueri. Dalam contoh ini, pengguna hanya dapat menggunakan: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. externalOptionsAllowList dapat berupa string kosong untuk memastikan bahwa hanya opsi yang ditentukan dalam koneksi Katalog Unity yang digunakan. URL dan host tidak pernah diizinkan untuk ditentukan oleh pengguna.

URL adalah satu-satunya opsi wajib saat membuat koneksi. Jika tidak ada daftar yang diizinkan yang ditentukan, daftar izin default digunakan yang berisi: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'.

Databricks merekomendasikan untuk menentukan kredensial dalam koneksi.

Langkah 3: Berikan `USE` hak istimewa

USE Berikan hak istimewa pada koneksi kepada pengguna:

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-name>;

Untuk informasi tentang mengelola koneksi yang ada, lihat Pengelolaan Koneksi untuk Lakehouse Federation.

Langkah 4: Mengkueri sumber data

Pengguna dengan USE CONNECTION hak istimewa dapat mengkueri sumber data menggunakan koneksi JDBC melalui Spark atau SQL API kueri jarak jauh. Pengguna dapat menambahkan opsi sumber data Spark apa pun yang didukung oleh driver JDBC dan ditentukan dalam externalOptionsAllowList koneksi JDBC (misalnya, dalam hal ini: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Untuk menampilkan opsi yang diizinkan, jalankan kueri berikut:

DESCRIBE CONNECTION <JDBC-connection-name>;

Phyton

df = (
  spark.read.format('jdbc')
  .option('databricks.connection', '<JDBC-connection-name>')
  .option('query', 'select * from <table_name>') # query in Database native SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in Database native SQL language - Option specified by querying user

Migration

Untuk bermigrasi dari beban kerja Spark Data Source API yang ada, Databricks merekomendasikan untuk melakukan hal berikut:

Hapus URL dan kredensial dari opsi di API Sumber Data Spark.
Tambahkan databricks.connection ke dalam opsi di Spark Data Source API.
Buat koneksi JDBC dengan URL dan kredensial yang sesuai.
Dalam koneksi, tentukan opsi yang harus statis dan tidak boleh ditentukan melalui permintaan dari pengguna.
Dalam koneksi externalOptionsAllowList, tentukan opsi sumber data yang harus disesuaikan atau dimodifikasi oleh pengguna pada waktu kueri dalam kode API Sumber Data Spark (misalnya, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Keterbatasan

API Sumber Data Spark

URL dan host tidak dapat disertakan dalam API Sumber Data Spark.
.option("databricks.connection", "<Connection_name>") diperlukan.
Opsi yang ditentukan dalam koneksi tidak dapat digunakan pada API Sumber Data dalam kode Anda pada waktu kueri.
Hanya opsi yang telah ditentukan dalam externalOptionsAllowList yang dapat digunakan oleh pengguna yang melakukan kueri.
Batas memori untuk driver JDBC adalah 400 MiB. Pertimbangkan menggunakan fetchSize yang lebih kecil jika batas tercapai.

Support

Sumber data Spark tidak didukung.
Alur Deklaratif Spark tidak didukung.
Dependensi koneksi saat pembuatan: java_dependencies hanya mendukung lokasi volume untuk JAR driver JDBC.
Dependensi koneksi pada kueri: Pengguna koneksi memerlukan READ akses ke volume tempat JAR driver JDBC berada.
Pada mode akses khusus (sebelumnya mode akses pengguna tunggal), Anda harus menjadi pemilik atau manajer koneksi untuk menggunakannya.
Sertifikat SSL tidak didukung.
Katalog asing tidak didukung dengan koneksi JDBC.

Authentication

Hanya autentikasi dasar yang didukung (nama pengguna dan kata sandi). Tidak ada dukungan untuk kredensial Katalog Unity, OAuth, atau kredensial layanan.

Jaringan

Sistem database target dan ruang kerja Azure Databricks tidak boleh berada di VPC yang sama.

Konektivitas jaringan

Konektivitas jaringan dari sumber daya komputasi Anda ke sistem database target diperlukan. Lihat Rekomendasi jaringan untuk Federasi Lakehouse untuk panduan jaringan umum.

Komputasi klasik: kluster standar dan khusus

VPC Azure Databricks dikonfigurasi untuk hanya mengizinkan kluster Spark. Untuk menyambungkan ke infrastruktur lain, tempatkan sistem database target di VPC yang berbeda dan gunakan peering VPC. Setelah peering VPC dibuat, periksa koneksi Anda dengan connectionTest UDF pada kluster atau gudang.

Jika ruang kerja Azure Databricks dan sistem database target Anda berada di VPC yang sama, Databricks merekomendasikan salah satu hal berikut ini:

Gunakan komputasi tanpa server.
Konfigurasikan database target Anda untuk memungkinkan lalu lintas TCP dan UDP melalui port 80 dan 443, dan tentukan port ini dalam koneksi.

Serverless

Saat menggunakan koneksi JDBC Anda pada komputasi tanpa server, konfigurasikan firewall untuk akses komputasi tanpa server untuk IP yang stabil, atau konfigurasikan konektivitas privat.

Uji konektivitas

Untuk menguji konektivitas antara komputasi Azure Databricks dan sistem database Anda, gunakan UDF berikut:

CREATE OR REPLACE TEMPORARY FUNCTION connectionTest(host string, port string) RETURNS string LANGUAGE PYTHON AS $$
import subprocess
try:
    command = ['nc', '-zv', host, str(port)]
    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    return str(result.returncode) + "|" + result.stdout.decode() + result.stderr.decode()
except Exception as e:
    return str(e)
$$;

SELECT connectionTest('<database-host>', '<database-port>');

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-31

Koneksi JDBC

Manfaat menggunakan koneksi JDBC

JDBC versus federasi kueri

Mengapa menggunakan sumber data JDBC versus PySpark?

Cara kerjanya

Sebelum Anda mulai

Langkah 1: Buat volume dan instal JDBC JAR

Langkah 2: Membuat koneksi JDBC

Eksplorer Katalog

SQL

Langkah 3: Berikan USE hak istimewa

Langkah 4: Mengkueri sumber data

Phyton

SQL

Migration

Keterbatasan

API Sumber Data Spark

Support

Authentication

Jaringan

Konektivitas jaringan

Komputasi klasik: kluster standar dan khusus

Serverless

Uji konektivitas

Saran dan Komentar

Sumber Daya Tambahan:

Langkah 3: Berikan `USE` hak istimewa