JDBC-Verbindung

Azure Databricks unterstützt das Herstellen einer Verbindung mit externen Datenbanken mithilfe von JDBC. Sie können eine JDBC Unity Catalog-Verbindung verwenden, um Daten aus einer Datenquelle mit der Spark Data Source API oder der Azure Databricks Remote Query SQL-API zu lesen und in sie zu schreiben. Die JDBC-Verbindung ist ein sicherbares Objekt im Unity-Katalog, das den JDBC-Treiber, die URL und Anmeldeinformationen für den Zugriff auf eine externe Datenbank angibt. Die JDBC-Verbindung wird über Unity Catalog-Computetypen hinweg unterstützt, einschließlich serverloser, Standardcluster, dedizierter Cluster und Databricks SQL.

Vorteile der Verwendung einer JDBC-Verbindung

• Lesen und Schreiben von Datenquellen mithilfe von JDBC und der Spark Data Source-API.
• Lesen aus Datenquellen mit JDBC mithilfe der Remote Query SQL-API.
• Gesteuerter Zugriff auf die Datenquelle mithilfe einer Unity-Katalogverbindung.
• Erstellen Sie die Verbindung nur einmal und verwenden Sie sie in jeder Unity-Katalog-Rechenressource wieder.
• Stabil für Spark- und Compute-Upgrades.
• Verbindungszugangsdaten werden vom Benutzer, der die Abfrage durchführt, ausgeblendet.

JDBC im Vergleich zur Abfrageföderation

JDBC ist eine Ergänzung zur Abfrageföderation. Databricks empfiehlt die Auswahl des Abfrageverbunds aus den folgenden Gründen:

• Der Abfrageverbund bietet differenzierte Zugriffssteuerungen und Governance auf Tabellenebene mithilfe eines fremden Katalogs. JDBC Unity-Katalogverbindung bietet Governance nur auf Verbindungsebene.
• Der Abfrageverbund pusht Spark-Abfragen nach unten, um eine optimale Abfrageleistung zu erzielen.

Wählen Sie jedoch die Verwendung einer JDBC Unity Catalog-Verbindung in den folgenden Szenarien:

• Ihre Datenbank wird vom Abfrageverbund nicht unterstützt.
• Sie möchten einen bestimmten JDBC-Treiber verwenden.
• Sie müssen mithilfe von Spark in die Datenquelle schreiben (Der Abfrageverbund unterstützt keine Schreibvorgänge).
• Sie benötigen mehr Flexibilität, Leistung und Parallelisierungssteuerung über Spark Data Source API-Optionen.
• Sie möchten SQL-Quellabfragen mithilfe der Spark-Option query nach unten weiterleiten.

Warum JDBC anstelle von PySpark-Datenquellen verwenden?

PySpark-Datenquellen sind eine Alternative zur JDBC Spark-Datenquelle.

Verwenden Sie eine JDBC-Verbindung:

• Wenn Sie die integrierte Spark JDBC-Unterstützung verwenden möchten.
• Wenn Sie einen sofort einsetzbaren JDBC-Treiber verwenden möchten, der bereits vorhanden ist.
• Wenn Sie eine Unity Catalog-Governance auf der Verbindungsebene benötigen.
• Wenn Sie eine Verbindung mit einem beliebigen Unity-Katalog-Computetyp herstellen möchten: Serverless, Standard, dedizierte SQL-API.
• Wenn Sie Ihre Verbindung mit Python-, Scala- und SQL-APIs verwenden möchten.

Verwenden Sie eine PySpark-Datenquelle:

• Wenn Sie die Flexibilität haben möchten, Ihre Spark-Datenquelle oder -Datensenke mit Python zu entwickeln und zu entwerfen.
• Wenn Sie sie nur in Notizbüchern oder PySpark-Workloads verwenden.
• Wenn Sie benutzerdefinierte Partitionierungslogik implementieren möchten.

Weder JDBC- noch PySpark-Datenquellen stellen dem Abfrageoptimierer Statistiken zur Verfügung, um die Reihenfolge der Operationen festzulegen.

Funktionsweise

Um eine Verbindung mit einer Datenquelle mithilfe einer JDBC-Verbindung herzustellen, installieren Sie den JDBC-Treiber auf Spark-Compute. Mit der Verbindung können Sie den JDBC-Treiber in einer isolierten Sandbox angeben und installieren, auf die Spark-Compute zugreifen kann, um die Spark-Sicherheit und Unity-Catalog-Governance sicherzustellen. Weitere Informationen zur Sandkastenumgebung finden Sie unter Wie erzwingt Databricks die Benutzerisolation?.

Bevor Sie anfangen

Um eine JDBC-Verbindung mit der Spark-Datenquellen-API in serverlosen und Standardclustern zu verwenden, müssen Sie zunächst die folgenden Anforderungen erfüllen:

Arbeitsbereichsanforderungen:

• Ein Für Unity-Katalog aktivierter Azure Databricks-Arbeitsbereich

Computeanforderungen:

• Netzwerkkonnektivität von Ihrer Rechenressource zu dem Zieldatenbanksystem. Siehe Netzwerkkonnektivität.
• Azure Databricks-Computing muss serverlos verwenden oder Databricks Runtime 17.3 LTS oder höher im Standardmodus oder im dedizierten Zugriffsmodus nutzen.
• SQL-Lagerhäuser müssen pro oder serverlos sein und 2025.35 oder höher verwenden.

Erforderliche Berechtigungen:

• Um eine Verbindung herzustellen, müssen Sie über die CREATE CONNECTION Berechtigung für den an den Arbeitsbereich angeschlossenen Metastore verfügen.
• CREATE oder MANAGE Zugriff auf ein Unity-Katalog-Volume durch den Verbindungsersteller.
• Volumenzugriff durch den Benutzer, der die Verbindung abfragt.
• Zusätzliche Berechtigungen werden in den folgenden aufgabenbasierten Abschnitten angegeben.

Authentifizierungsmethoden

Schritt 1: Erstellen eines Volumes und Installieren des JDBC-JAR

Die JDBC-Verbindung liest und installiert den JDBC-Treiber-JAR aus einem Unity Catalog-Volume.

1. Wenn Sie keinen Schreib- und Lesezugriff auf ein vorhandenes Volume haben, erstellen Sie ein neues Volume:

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. Laden Sie den JDBC-Treiber JAR auf das Volume hoch.

3. Gewähren Sie Lesezugriff auf das Volume für die Benutzer, die die Verbindung abfragen:

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

Schritt 2: Erstellen einer JDBC-Verbindung

Eine JDBC-Verbindung ist ein securable object in Unity Catalog. Es legt den JDBC-Treiber, den URL-Pfad, die Anmeldeinformationen für den Zugriff auf ein externes Datenbanksystem und zugelassene Optionen fest, die der anfragende Benutzer angeben kann. Verwenden Sie zum Erstellen einer Verbindung den Katalog-Explorer oder den CREATE CONNECTION SQL-Befehl in einem Azure Databricks-Notizbuch oder dem SQL-Abfrage-Editor für Databricks. Siehe Authentifizierungsmethoden für die unterstützten Authentifizierungsmethoden.

Erforderliche Berechtigungen: Metastore-Administrator oder Benutzer mit der Berechtigung „CREATE CONNECTION“.

Bevor Sie eine Verbindung erstellen, beachten Sie Folgendes:

• Die URL und die Anmeldeinformationen sind die einzigen erforderlichen Optionen. Betten Sie anmeldeinformationen nicht in die URL ein, da Protokolle oder Fehler sie verfügbar machen können. Verwenden Sie die spezifischen Anmeldedatenoptionen für die von Ihnen gewählte Authentifizierungsmethode.
• Verwenden Sie externalOptionsAllowList, um zu steuern, welche Optionen für Spark-Datenquellen Benutzer zum Zeitpunkt der Abfrage angeben können. Wenn nicht angegeben, ist die Standardeinstellung 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Legen Sie sie auf eine leere Zeichenfolge fest, um Benutzer auf die in der Verbindung definierten Optionen zu beschränken. Benutzer können niemals angeben url oder host.

Katalog-Explorer

1. Klicken Sie im Azure Databricks-Arbeitsbereich auf das Katalog.

2. Klicken Sie auf Verbinden, und klicken Sie dann auf "Verbindungen".

3. Klicken Sie auf Verbindung herstellen.

4. Geben Sie auf der Seite Verbindungsgrundlagen des Assistenten Verbindung einrichten einen benutzerfreundlichen Verbindungsnamen ein.

5. Wählen Sie unter VerbindungstypJDBC aus.

6. (Optional) Fügen Sie einen Kommentar hinzu.

7. Klicke auf Weiter.

8. Geben Sie auf der Seite "Verbindungsdetails " die folgenden Verbindungseigenschaften ein:

   Property	Description
   Url	Die JDBC-URL für Ihre Datenbank in der Form jdbc:subprotocol:subname (zum Beispiel jdbc:oracle:thin:@<host>:<port>:<SID>).
   Java Abhängigkeiten	Die JAR-Dateien des JDBC-Treibers aus Unity Catalog-Volumes. Klicken Sie auf „JAR-Abhängigkeit hinzufügen“, um jede JAR-Datei hinzuzufügen (z. B. /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
   Liste zugelassener externer Optionen	Durch Trennzeichen getrennte Liste der Spark-Datenquellenoptionen , die von Benutzern zur Abfragezeit angegeben werden können. Wird standardmäßig auf dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions festgelegt. Legen Sie den Wert auf einen leeren Wert fest, um benutzer nur auf die optionen zu beschränken, die für die Verbindung definiert sind.
   Weitere Optionen	Beliebige JDBC-Treiberoptionen werden in Form von Schlüssel-Wert-Paaren an den Treiber weitergegeben. Verwenden Sie diesen Abschnitt, um Datenbankanmeldeinformationen (z. B. Schlüssel user und Schlüssel password) und alle anderen treiberspezifischen Eigenschaften festzulegen. Wechseln Sie nach Bedarf zwischen UI- und JSON-Eingabemodi .

9. Klicken Sie auf Verbindung herstellen.

SQL

Verwenden Sie den CREATE CONNECTION SQL-Befehl in einem Notizbuch oder im SQL-Abfrage-Editor von 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'
);

Der Verbindungsbesitzer oder -manager kann einer Verbindung alle zusätzlichen Optionen hinzufügen, die vom JDBC-Treiber unterstützt werden. Aus Sicherheitsgründen können optionen, die in der Verbindung definiert sind, zur Abfragezeit nicht überschrieben werden.

Schritt 3: Gewähren der USE Berechtigung

Gewähren Sie die USE Berechtigung auf die Verbindung an die Benutzer:

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

Informationen zum Verwalten vorhandener Verbindungen finden Sie unter Verwalten von Verbindungen für Lakehouse Federation.

Schritt 4: Abfragen der Datenquelle

Benutzer mit den USE CONNECTION Berechtigungen können die Datenquelle über die JDBC-Verbindung mithilfe von Spark oder der SQL-API für Remoteabfragen abfragen. Benutzer können alle Spark-Datenquellenoptionen hinzufügen, die vom JDBC-Treiber unterstützt werden und in der JDBC-Verbindung angegeben sind (z. B. in diesem Fall: externalOptionsAllowList). Führen Sie die folgende Abfrage aus, um die zulässigen Optionen anzuzeigen:

DESCRIBE CONNECTION <JDBC-connection-name>;

Python

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

Um von vorhandenen Spark Data Source API-Workloads zu migrieren, empfiehlt Databricks Folgendes:

• Entfernen Sie die URL und Anmeldeinformationen aus den Optionen in der Spark-Datenquellen-API.
• Fügen Sie databricks.connection in den Optionen der Spark-Datenquellen-API hinzu.
• Erstellen Sie eine JDBC-Verbindung mit der entsprechenden URL und den entsprechenden Anmeldeinformationen.
• Geben Sie in der Verbindung die Optionen an, die statisch sein sollen und nicht durch Abfragen von Benutzern angegeben werden sollen.
• Geben Sie im Verbindungscode externalOptionsAllowList die Datenquellenoptionen an, die Benutzer bei der Abfrage im Spark Data Source API-Code anpassen oder ändern sollten (z. B. 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Einschränkungen

Spark-Datenquellen-API

• DIE URL und der Host können nicht in die Spark-Datenquellen-API aufgenommen werden.
• .option("databricks.connection", "<Connection_name>") ist erforderlich.
• In der Verbindung definierte Optionen können nicht zur Abfragezeit in der Datenquellen-API verwendet werden.
• Nur die in der externalOptionsAllowList Datei angegebenen Optionen können von Benutzern bei Abfragen verwendet werden.
• Die Speichergrenze für den JDBC-Treiber beträgt 400 MiB. Erwägen Sie die Verwendung eines kleineren fetchSize Grenzwerts, wenn der Grenzwert erreicht ist.

Support

• Spark-Datenquellen werden nicht unterstützt.
• Lakeflow Spark Declarative Pipelines wird nicht unterstützt.
• Verbindungsabhängigkeit bei der Erstellung: java_dependencies unterstützt nur Volume-Standorte für JDBC-Treiber-JARs.
• Verbindungsabhängigkeit bei Abfrage: Der Verbindungsbenutzer benötigt READ Zugriff auf das Volume, auf dem sich der JDBC-Treiber-JAR befindet.
• Im dedizierten Zugriffsmodus (vormals Einzelbenutzerzugriffsmodus) müssen Sie Besitzer oder Vorgesetzter der Verbindung sein, um sie zu verwenden.
• SSL-Zertifikate werden nicht unterstützt.
• Fremdkataloge werden nicht mit JDBC-Verbindungen unterstützt.

Authentifizierung

• Dieser Konnektor unterstützt statische Anmeldedaten und OAuth für die Maschine-zu-Maschine-Kommunikation. Es unterstützt weder Unity Catalog-Anmeldeinformationen noch Serviceanmeldeinformationen.

Vernetzung

• Das Zieldatenbanksystem und der Azure Databricks Arbeitsbereich können nicht im gleichen VNet vorhanden sein.

Netzwerkkonnektivität

Netzwerkkonnektivität von Ihrer Computeressource mit dem Zieldatenbanksystem ist erforderlich. Allgemeine Netzwerkrichtlinien finden Sie in den Netzwerkempfehlungen für lakehouse Federation .

Klassische Berechnung: Standard- und dedizierte Cluster

Azure Databricks VNets sind so konfiguriert, dass nur Spark-Cluster zulässig sind. Um eine Verbindung mit einer anderen Infrastruktur herzustellen, platzieren Sie das Zieldatenbanksystem in einem anderen VNet und verwenden VNet-Peering. Nachdem das VNet-Peering hergestellt wurde, überprüfen Sie Ihre Konnektivität mithilfe der connectionTest UDF auf dem Cluster oder im Warehouse.

Wenn sich Ihre Azure Databricks Arbeitsbereichs- und Zieldatenbanksysteme im selben VNet befinden, empfiehlt Databricks eine der folgenden Optionen:

• Verwenden Sie serverlose Berechnung.
• Konfigurieren Sie Ihre Zieldatenbank so, dass TCP- und UDP-Datenverkehr über die Ports 80 und 443 zulässig ist, und geben Sie diese Ports in der Verbindung an.

Serverlos

Konfigurieren Sie bei der Verwendung Ihrer JDBC-Verbindung auf serverlosem Compute eine Firewall für den Zugriff auf serverless Compute für stabile IP-Adressen oder konfigurieren Sie private Konnektivität.

Konnektivitätstest

Verwenden Sie die folgende UDF, um die Konnektivität zwischen azure Databricks compute und Ihrem Datenbanksystem zu testen:

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

Die folgenden häufig gestellten Fragen beziehen sich auf das Predicate-Pushdown-Verhalten für JDBC-Verbindungen.

Unterstützt JDBC Predicate Pushdown?

Yes. Filter werden standardmäßig sowohl für die Spark Data Source API (format('jdbc')) als auch für die remote_query SQL-Funktion an die Remotedatenbank weitergegeben. Welche Prädikate nach unten weitergegeben werden können, hängt vom JDBC-Treiber und vom Dialekt ab. Führen Sie daher EXPLAIN für Ihre Abfrage aus und prüfen Sie den physischen Plan, um zu bestätigen, welche Filter an die Quelle weitergegeben werden. Für die remote_query SQL-Funktion können Sie bestimmte Pushdowns (Filter, Limits, Offsets und Aggregate) mit Optionen wie pushdown.filters.enabled steuern; sie alle sind standardmäßig aktiviert.

Predicate Pushdown ist von der Bereitstellung von Tabellenstatistiken für den Abfrageoptimierer zu unterscheiden. JDBC- und PySpark-Datenquellen stellen dem Query-Optimierer keine Statistiken zur Verfügung, die ihm helfen, die Reihenfolge der Operationen festzulegen, unabhängig davon, ob Prädikate nach unten weitergegeben werden.