Connessione JDBC

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.

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.
• Si desidera inviare le query SQL di origine 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é le sorgenti dati JDBC né quelle PySpark espongono statistiche all'ottimizzatore di query per aiutarlo a selezionare l'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.

Metodi di autenticazione

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.

1. 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
   

2. Caricare il file JAR del driver JDBC nel volume.

3. 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 proteggibile in Unity Catalog. Specifica il driver JDBC, il percorso URL, le credenziali per l'accesso a un sistema di database esterno e le opzioni elencate che l'utente che esegue query può specificare. 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. Vedere Metodi di autenticazione per i metodi di autenticazione supportati.

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

Prima di creare una connessione, tenere presente quanto segue:

• L'URL e le credenziali sono le uniche opzioni necessarie. Non incorporare le credenziali nell'URL, perché i log o gli errori possono esporli. Usare le opzioni relative alle credenziali dedicate per il metodo di autenticazione scelto.
• Usare externalOptionsAllowList per controllare le opzioni dell'origine dati Spark che gli utenti possono specificare in fase di query. Se non specificato, il valore predefinito è 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Impostarla su una stringa vuota per limitare gli utenti solo alle opzioni definite nella connessione. Gli utenti non possono mai specificare url o host.

Esploratore di cataloghi

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.

2. Fare clic sull'icona , quindi su Connetti, e infine su Connessioni.

3. Fai clic su Crea connessione.

4. Nella pagina Elementi di base della connessione della Procedura guidata di configurazione della connessione, inserisci un nome di connessione facile da usare.

5. In Tipo di connessione selezionare JDBC.

6. (Facoltativo) Aggiungere un commento.

7. Fare clic su Avanti.

8. Nella pagina Dettagli connessione immettere le proprietà di connessione seguenti:

   Proprietà	Description
   Url	URL JDBC per il database, nel formato jdbc:subprotocol:subname , ad esempio jdbc:oracle:thin:@<host>:<port>:<SID>.
   Java dipendenze	I file JAR del driver JDBC dai volumi di Unity Catalog. Fare clic su Aggiungi dipendenza JAR per aggiungere ogni file JAR (ad esempio, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
   Elenco di opzioni esterne consentite	Elenco delimitato da virgole delle opzioni dell'origine dati Spark che possono essere specificate dagli utenti in fase di query. Di default è dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. Impostare su un valore vuoto per limitare gli utenti solo alle opzioni definite nella connessione.
   Opzioni aggiuntive	Opzioni arbitrarie del driver JDBC trasmesse al driver come coppie chiave-valore. Usare questa sezione per impostare le credenziali del database ( ad esempio chiave user e chiave password) e qualsiasi altra proprietà specifica del driver. Passare da un'interfaccia utente a una modalità di input JSON in base alle esigenze.

9. Fai clic su Crea connessione.

SQL

Usare il CREATE CONNECTION comando SQL in un notebook o nell'editor di query SQL di Databricks.

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

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

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>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint '<https://authorization-server.com/oauth/token>',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '<driver-token-parameter-name>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

CREATE CONNECTION postgres_oauth_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/postgresql-42.7.3.jar"]'
)
OPTIONS (
  url 'jdbc:postgresql://<host>:<port>/<database>?sslmode=require',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint 'https://authorization-server.com/oauth/token',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '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.

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 source SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in source 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.
• Le pipeline dichiarative di Lakeflow Spark non sono supportate.
• 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

• Questo connettore supporta credenziali statiche e OAuth machine-to-machine. Non supporta le credenziali del catalogo Unity o le credenziali del servizio.

Rete

• Il sistema di database di destinazione e l'area di lavoro Azure Databricks non possono trovarsi nella stessa rete virtuale.

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 reti virtuali di Azure Databricks sono configurate per consentire esclusivamente i cluster Spark. Per connettersi a un'altra infrastruttura, collocare il sistema di database di destinazione in una VNet diversa e utilizzare il peering VNet. Dopo aver configurato il peering della rete virtuale, controllare la connettività con la connectionTest funzione definita dall'utente nel cluster o nel data warehouse.

Se l'area di lavoro Azure Databricks e i sistemi di database di destinazione si trovano nella stessa rete virtuale, 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>');

FAQ

Le domande frequenti seguenti illustrano il comportamento di pushdown del predicato per le connessioni JDBC.

JDBC supporta il pushdown dei predicati?

Yes. Per impostazione predefinita, i filtri vengono applicati direttamente al database remoto sia per l'API Spark Data Source (format('jdbc')) sia per la funzione SQL remote_query. Quali predicati possono essere delegati dipende dal driver JDBC e dal dialetto, quindi esegui EXPLAIN sulla query e controlla il piano fisico per confermare quali filtri vengono delegati all'origine dati. Per la remote_query funzione SQL, è possibile controllare specifici pushdown (filtri, limiti, offset e aggregazioni) con opzioni come pushdown.filters.enabled; tutte sono abilitate per impostazione predefinita.

Il pushdown dei predicati è distinto dall'esposizione delle statistiche delle tabelle all'ottimizzatore di query. Le fonti di dati JDBC e PySpark non forniscono statistiche all'ottimizzatore di query per aiutare a selezionare l'ordine delle operazioni, indipendentemente dal fatto che venga applicato o meno il pushdown dei predicati.