Connessione JDBC

Annotazioni

Questa funzionalità è una versione beta a livello di area di lavoro in Databricks Runtime 17.3 e versioni successive. Per abilitare questa funzionalità nell'area di lavoro, vedere Gestire le anteprime a livello di area di lavoro.

Azure Databricks supporta la connessione a database esterni tramite JDBC. È possibile usare una connessione del catalogo Unity di JDBC per leggere e scrivere in un'origine dati con l'API Origine dati Spark o l'API SQL query remota di Azure Databricks. La connessione JDBC è un oggetto a protezione diretta in Unity Catalog che specifica il driver JDBC, il percorso URL e le credenziali per l'accesso a un database esterno. La connessione JDBC è supportata tra i tipi di calcolo di Unity Catalog, inclusi cluster serverless, standard, cluster dedicati e Databricks SQL.

Vantaggi dell'uso di una connessione JDBC

Leggere e scrivere su origini dati mediante JDBC con il Spark Data Source API.
Leggere da origini dati con JDBC usando l'API SQL Remote Query.
Regola l'accesso all'origine dati usando una connessione al catalogo Unity.
Creare la connessione una volta e riutilizzarla in qualsiasi calcolo del catalogo Unity.
Stabile per gli aggiornamenti di Spark e di calcolo.
Le credenziali di connessione sono nascoste all'utente che esegue query.

JDBC e federazione di query

JDBC è complementare alla federazione delle query. Databricks consiglia di scegliere la federazione delle query per i motivi seguenti:

La federazione delle query fornisce controlli di accesso e governance granulari a livello di tabella usando un catalogo esterno. La connessione al catalogo unity di JDBC fornisce la governance solo a livello di connessione.
La federazione delle query delega l'elaborazione delle query Spark per garantire prestazioni delle query ottimali.

Annotazioni

La federazione delle query supporta molti database comuni, tra cui Oracle, MySQL, PostgreSQL, SQL Server e Snowflake. Se il database è supportato, Databricks consiglia di usare la federazione delle query anziché una connessione JDBC. Per l'elenco completo dei database supportati, vedere Lakehouse Federation.See Lakehouse Federation for the full list of supported databases.

Tuttavia, scegliere di usare una connessione del catalogo Unity di JDBC negli scenari seguenti:

Il database non è supportato dalla federazione delle query.
Si vuole usare un driver JDBC specifico.
È necessario scrivere nell'origine dati usando Spark (la federazione delle query non supporta le scritture).
È necessaria maggiore flessibilità, prestazioni e controllo della parallelizzazione tramite le opzioni dell'API origine dati Spark.
Vuoi ottimizzare le query con l'opzione Spark query.

Perché usare JDBC rispetto alle origini dati PySpark?

Le origini dati PySpark sono un'alternativa all'origine dati JDBC Spark.

Usare una connessione JDBC:

Se si vuole usare il supporto JDBC Spark predefinito.
Se si desidera utilizzare un driver JDBC già pronto.
Se è necessaria la governance del catalogo Unity a livello di connessione.
Per connettersi da qualsiasi tipo di calcolo supportato da Unity Catalog: serverless, standard, dedicato, API SQL.
Se si vuole usare la connessione con Python, Scala e API SQL.

Usare un'origine dati PySpark:

Se si vuole avere la flessibilità necessaria per sviluppare e progettare la sorgente di dati Spark o il sink di dati usando Python.
Se lo utilizzi solo nei notebook o nei carichi di lavoro PySpark.
Se si vuole implementare la logica di partizionamento personalizzata.

Né JDBC né le origini dati PySpark supportano il pushdown del predicato. Inoltre, non espongono statistiche a Query Optimizer per facilitare la selezione dell'ordine delle operazioni.

Come funziona

Per connettersi a un'origine dati usando una connessione JDBC, installare il driver JDBC nel calcolo Spark. La connessione consente di specificare e installare il driver JDBC in una sandbox isolata accessibile dal calcolo Spark per garantire la sicurezza di Spark e la governance del catalogo Unity. Per altre informazioni sul sandboxing, consultare Come fa Databricks a garantire l'isolamento degli utenti?.

Prima di iniziare

Per usare una connessione JDBC con l'API origine dati Spark in cluster serverless e standard, è prima necessario soddisfare i requisiti seguenti:

Requisiti dell'area di lavoro:

Un'area di lavoro di Azure Databricks abilitata per Unity Catalog

Requisiti di calcolo:

Connettività di rete dalla risorsa di calcolo al sistema di database di destinazione. Vedere Connettività di rete.
Il calcolo di Azure Databricks deve usare serverless o Databricks Runtime 17.3 LTS o versione successiva in modalità standard o in modalità di accesso dedicato.
I warehouse SQL devono essere pro o serverless e devono usare la versione 2025.35 o successiva.

Autorizzazioni necessarie:

Per creare una connessione, è necessario disporre del CREATE CONNECTION privilegio per il metastore collegato all'area di lavoro.
CREATE o MANAGE accesso a un volume del catalogo Unity da parte del creatore della connessione.
Accesso al volume da parte dell'utente che interroga il collegamento.
Le autorizzazioni aggiuntive vengono specificate in ogni sezione basata su attività che segue.

Passaggio 1: Creare un volume e installare il file JAR JDBC

La connessione JDBC legge e installa il file JAR del driver JDBC da un volume di Unity Catalog.

Se non si ha accesso in scrittura e lettura a un volume esistente, creare un nuovo volume:
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
Caricare il file JAR del driver JDBC nel volume.

Concedere l'accesso in lettura al volume agli utenti che interrogano la connessione.

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

Passaggio 2: Creare una connessione JDBC

Una connessione JDBC è un oggetto a protezione diretta in Unity Catalog che specifica il driver JDBC, il percorso URL e le credenziali per l'accesso a un sistema di database esterno e consente l'uso delle opzioni elencate dall'utente che esegue query. Per creare una connessione, usare Catalog Explorer o il CREATE CONNECTION comando SQL in un notebook di Azure Databricks o nell'editor di query SQL di Databricks.

Annotazioni

È anche possibile usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare una connessione. Vedere POST /api/2.1/unity-catalog/connections e i comandi del Unity Catalog.

Autorizzazioni necessarie: Amministratore o utente Metastore con il privilegio CREATE CONNECTION.

Esploratore di cataloghi

Nell'area di lavoro di Azure Databricks fare clic Catalogo.
Nella parte superiore del riquadro Catalogo fare clic Aggiungi e selezionare Crea una connessione dal menu.
Nella pagina Elementi di base della connessione della Procedura guidata di configurazione della connessione, inserisci un nome di connessione facile da usare.
Selezionare un tipo di connessionedi JDBC.
(Facoltativo) Aggiungere un commento.
Fare clic su Avanti.
Nella pagina Autenticazione immettere le proprietà di connessione seguenti:
- URL JDBC: URL di connessione JDBC per il database, ad esempio jdbc:oracle:thin:@<host>:<port>:<SID>.
- Utente: nome utente del database.
- Password: password del database.
- Percorso del driver JDBC: percorso del volume del catalogo Unity per il file JAR del driver JDBC , ad esempio /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar.
Fai clic su Crea connessione.

SQL

Eseguire il comando seguente in un notebook o nell'editor di query SQL, modificando il volume, l'URL, le credenziali e 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>;

Esempio: connessione Oracle JDBC

Nell'esempio seguente viene creata una connessione JDBC a un database Oracle usando il driver thin Oracle. Scaricare il file JAR del driver JDBC Oracle (ad esempio , ojdbc11.jar) dalla pagina di download di Oracle JDBC e caricarlo in un volume del catalogo Unity prima di eseguire questo comando.

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

Il proprietario o la gestione della connessione può aggiungere alla connessione eventuali opzioni aggiuntive supportate dal driver JDBC.

Per motivi di sicurezza, le opzioni definite nella connessione non possono essere sottoposte a override in fase di query. Gli utenti possono specificare solo le opzioni dell'origine dati Spark che non sono già definite nella connessione.

externalOptionsAllowList consente all'autore della connessione di specificare le opzioni dell'origine dati Spark che gli utenti possono fornire in fase di query. In questo esempio gli utenti possono usare solo : 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. externalOptionsAllowList Può essere una stringa vuota per assicurarsi che vengano usate solo le opzioni specificate nella connessione al catalogo Unity. L'URL e l'host non possono mai essere specificati dagli utenti.

URL è l'unica opzione obbligatoria durante la creazione della connessione. Se non viene specificato alcun elenco di elementi consentiti, viene usato un elenco di elementi consentiti predefinito che contiene: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'.

Databricks consiglia di specificare le credenziali nella connessione.

Passaggio 3: Concedere il `USE` privilegio

Concedere il USE privilegio per la connessione agli utenti:

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

Per informazioni sulla gestione delle connessioni esistenti, vedere Gestione delle connessioni per Lakehouse Federation.

Passaggio 4: Eseguire query sull'origine dati

Gli utenti con privilegi USE CONNECTION possono eseguire query sull'origine dati usando la connessione JDBC tramite Spark o l'API SQL delle query remote. Gli utenti possono aggiungere qualsiasi opzione dell'origine dati Spark supportata dal driver JDBC e specificata in externalOptionsAllowList nella connessione JDBC, ad esempio in questo caso: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Per visualizzare le opzioni consentite, eseguire la query seguente:

DESCRIBE CONNECTION <JDBC-connection-name>;

Pitone

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

Per eseguire la migrazione da carichi di lavoro dell'API origine dati Spark esistenti, Databricks consiglia di eseguire le operazioni seguenti:

Rimuovere l'URL e le credenziali dalle opzioni nell'API origine dati Spark.
Aggiungi le databricks.connection opzioni nell'API di origine dati di Spark.
Creare una connessione JDBC con l'URL e le credenziali corrispondenti.
Nella connessione, specificare le opzioni che devono essere statiche e non devono essere specificate chiedendolo agli utenti.
Nella connessione externalOptionsAllowList, specificare le opzioni dell'origine dati che devono essere modificate dagli utenti al momento dell'interrogazione nel codice dell'API Origine dati Spark (ad esempio, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Limitazioni

API origine dati Spark

L'URL e l'host non possono essere inclusi nell'API origine dati Spark.
.option("databricks.connection", "<Connection_name>") è obbligatorio.
Le opzioni definite nella connessione non possono essere usate nell'API origine dati nel codice in fase di query.
È possibile utilizzare solo le opzioni specificate in externalOptionsAllowList durante l'interrogazione degli utenti.
Il limite di memoria per il driver JDBC è 400 MiB. Prendere in considerazione l'uso di un valore minore fetchSize se viene raggiunto il limite.

Support

Le origini dati Spark non sono supportate.
La pipeline dichiarativa Spark non è supportata.
Dipendenza della connessione durante la creazione: java_dependencies supporta solo e unicamente le posizioni dei volumi per i file JAR del driver JDBC.
Dipendenza di connessione alla query: l'utente della connessione deve READ accedere al volume in cui si trova il file JAR del driver JDBC.
In modalità di accesso dedicato (in precedenza modalità accesso utente singolo), è necessario essere un proprietario o un gestore della connessione per usarlo.
I certificati SSL non sono supportati.
I cataloghi esterni non sono supportati con le connessioni JDBC.

Authentication

È supportata solo l'autenticazione di base (nome utente e password). Non è disponibile alcun supporto per le credenziali del catalogo Unity, OAuth o del servizio.

Rete

Il sistema di database di destinazione e l'area di lavoro di Azure Databricks non possono trovarsi nello stesso VPC.

Connettività di rete

È necessaria la connettività di rete dalla risorsa di calcolo al sistema di database di destinazione. Per indicazioni generali sulla rete, vedere Raccomandazioni sulla rete per la Federazione Lakehouse.

Risorse di calcolo classiche: cluster standard e dedicati

Le VPN di Azure Databricks sono configurate per consentire solo cluster Spark. Per connettersi a un'altra infrastruttura, posizionare il sistema di database di destinazione in un VPC diverso e usare il peering VPC. Dopo aver stabilito il peering VPC, controllare la connettività con la UDF (funzione definita dall'utente) connectionTest nel cluster o nel data warehouse.

Se l'area di lavoro di Azure Databricks e i sistemi di database di destinazione si trovano nello stesso VPC, Databricks consiglia una delle opzioni seguenti:

Usare l'ambiente di calcolo serverless.
Configurare il database di destinazione per consentire il traffico TCP e UDP sulle porte 80 e 443 e specificare queste porte nella connessione.

Serverless

Quando si usa la connessione JDBC nel calcolo serverless, configurare un firewall per l'accesso al calcolo serverless con indirizzi IP fissi o configurare la connettività privata.

Test di connettività

Per testare la connettività tra le risorse di calcolo di Azure Databricks e il sistema di database, usare la seguente funzione definita dall'utente (UDF):

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

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-15

Condividi tramite

Connessione JDBC

Vantaggi dell'uso di una connessione JDBC

JDBC e federazione di query

Perché usare JDBC rispetto alle origini dati PySpark?

Come funziona

Prima di iniziare

Passaggio 1: Creare un volume e installare il file JAR JDBC

Passaggio 2: Creare una connessione JDBC

Esploratore di cataloghi

SQL

Passaggio 3: Concedere il USE privilegio

Passaggio 4: Eseguire query sull'origine dati

Pitone

SQL

Migration

Limitazioni

API origine dati Spark

Support

Authentication

Rete

Connettività di rete

Risorse di calcolo classiche: cluster standard e dedicati

Serverless

Test di connettività

Commenti e suggerimenti

Risorse aggiuntive

Passaggio 3: Concedere il `USE` privilegio