Databricks JDBC-Treiber (OSS)

Azure Databricks bietet einen Open Source (OSS) JDBC-Treiber, mit dem Sie Tools, wie DataGrip, DBeaver und SQL Workbench/J über die branchenübliche Spezifikation Java Database Connectivity (JDBC) mit Azure Databricks verbinden können, um auf Datenbankmanagementsysteme zuzugreifen.

In diesem Treiber sind die JDBC (Java Database Connectivity)-APIs implementiert. Er bietet Kernfunktionen wie OAuth und Cloud Fetch sowie Features wie die Unity Catalog-Volumeerfassung. Er führt den nativen Abfragemodus aus, unterstützt native parametrisierte Abfragen und kann mit Anweisungsausführungs-APIs ausgeführt werden, wodurch das nützliche Feature für die Aufbewahrung von Abfrageergebnissen oder Thrift bereitgestellt wird.

Dieser Artikel enthält Informationen zur Installation und Verwendung des Databricks JDBC-Treibers (OSS). Informationen zu nicht-OSS Databricks JDBC-Treibern finden Sie unter Databricks JDBC-Treiber.

Anforderungen

Für die Verwendung des Databricks JDBC-Treibers (OSS) müssen die folgenden Anforderungen erfüllt sein:

• Java Runtime Environment (JRE) 11.0 oder höher CI-Tests werden auf JRE 11, 17 und 21 unterstützt.

Installieren des Treibers

Der Databricks JDBC-Treiber (OSS) wird im Maven Repository veröffentlicht. Die neueste Version ist 0.9.6-oss.

Um den Treiber zu installieren, verwenden Sie eine der folgenden Vorgehensweisen:

• Bei Maven-Projekten fügen Sie die folgende Abhängigkeit zur pom.xml-Datei des Projekts hinzu, um Maven anzuweisen, den JDBC-Treiber automatisch in der angegebenen Version herunterzuladen:

  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-jdbc</artifactId>
    <version>0.9.6-oss</version>
    <scope>runtime</scope>
  </dependency>
  

• Bei Gradle-Projekten fügen Sie die folgende Abhängigkeit zur Build-Datei des Projekts hinzu, um Gradle anzuweisen, den JDBC-Treiber mit der angegebenen Version automatisch herunterzuladen:

  implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
  

Die Syntax der Abhängigkeiten für andere Projekttypen und die aktuelle Versionsnummer des Databricks JDBC-Treibers (OSS) finden Sie im Maven Repository.

Konfigurieren der Verbindungs-URL

Um eine Verbindung zu Ihrem Azure Databricks-Arbeitsbereich mit dem JDBC-Treiber herzustellen, müssen Sie eine JDBC-Verbindungs-URL angeben, die verschiedene Verbindungseinstellungen wie den Server-Hostnamen Ihres Azure Databricks-Arbeitsbereichs, die Einstellungen für die Computeressourcen und die Authentifizierungsdaten für die Verbindung zum Arbeitsbereich enthält.

Sie können den Wert dieser Eigenschaften in der JDBC-Verbindungs-URL festlegen, sie festlegen und an die Methode DriverManager.getConnection übergeben oder eine Kombination aus beidem. Lesen Sie in der Dokumentation des Anbieters nach, wie Sie am besten eine Verbindung mit Ihrer spezifischen Anwendung, Ihrem Client, SDK, API oder SQL-Tool herstellen.

Die JDBC-Verbindungs-URL muss folgendes Format aufweisen. Bei Eigenschaften wird die Groß-/Kleinschreibung nicht berücksichtigt.

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

Alternativ können Sie die Einstellungen mithilfe der Klasse java.util.Properties oder einer Kombination angeben:

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

Die Elemente der Verbindungs-URL werden in der folgenden Tabelle beschrieben. Weitere Informationen zu zusätzlichen Eigenschaften, einschließlich Authentifizierungseigenschaften, finden Sie in den folgenden Abschnitten. Bei URL-Elementen und -Eigenschaften wird die Groß-/Kleinschreibung nicht beachtet.

So rufen Sie die JDBC-Verbindungs-URL für einen Azure Databricks Cluster ab:

1. Melden Sie sich bei Ihrem Azure Databricks-Arbeitsbereich an.
2. Wählen Sie in der Randleiste Compute und dann den Namen des Zielclusters aus.
3. Erweitern Sie auf der Registerkarte Konfiguration die Option Erweiterte Optionen.
4. Klicken Sie auf die Registerkarte JDBC/ODBC.
5. Kopieren Sie die JDBC-URL, um sie als JDBC-Verbindungs-URL zu verwenden, oder erstellen Sie die URL aus Werten in den Feldern Hostname des Servers, Port und HTTP-Pfad.

So rufen Sie die JDBC-Verbindungs-URL für ein Databricks SQL Warehouse ab:

1. Melden Sie sich bei Ihrem Azure Databricks-Arbeitsbereich an.
2. Wählen Sie in der Randleiste SQL Warehousesund dann den Namen des Ziel-Warehouse aus.
3. Wählen Sie die Registerkarte Verbindungsdetails aus.
4. Kopieren Sie die JDBC-URL, um sie als JDBC-Verbindungs-URL zu verwenden, oder erstellen Sie die URL aus Werten in den Feldern Hostname des Servers, Port und HTTP-Pfad.

Authentifizieren des Treibers

Sie können die JDBC-Treiberverbindung mithilfe eines der folgenden Authentifizierungsmechanismen authentifizieren:

• OAuth U2M-Authentifizierung (User-to-Machine) (Empfohlen)
• OAuth-M2M-Authentifizierung
• Persönliches Zugriffstoken für Azure Databricks

OAuth U2M-Authentifizierung (User-to-Machine)

Der JDBC-Treiber unterstützt die OAuth U2M (User-to-Machine)-Authentifizierung für die Echtzeit-Anmeldung von Menschen und die Zustimmung zur Authentifizierung des Databricks-Benutzerkontos. Dies wird auch als browserbasierte OAuth-Authentifizierung bezeichnet.

Azure Databricks hat die OAuth-Client-ID databricks-sql-jdbc für Kunden erstellt. Dies ist auch die Standard-OAuth-Client-ID, die im JDBC-Treiber verwendet wird. Um die OAuth U2M-Authentifizierung zu konfigurieren, fügen Sie einfach die folgenden Eigenschaften zu Ihrer bestehenden JDBC-Verbindungs-URL oder Ihrem java.util.Properties-Objekt hinzu:

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Der JDBC-Treiber unterstützt die OAuth-M2M-Authentifizierung (Machine-to-Machine) mit einem Azure Databricks-Dienstprinzipal. Dies wird auch OAuth 2.0-Authentifizierung mit Clientanmeldeinformationen genannt. Weitere Informationen finden Sie unter Authentifizierung des Zugriffs bei Azure Databricks mit einem Dienstprinzipal unter Verwendung von OAuth (OAuth M2M).

So konfigurieren Sie die OAuth M2M- oder OAuth 2.0-Authentifizierung mit Clientanmeldeinformationen:

1. Erstellen Sie einen durch Microsoft Entra ID verwalteten Dienstprinzipal, und weisen Sie ihn dann Azure Databricks-Konten und -Arbeitsbereichen zu. Details hierzu finden Sie unter Verwalten von Dienstprinzipalen.

   Wichtig

   Der Databricks JDBC-Treiber (OSS) unterstützt Azure Databricks-OAuth-Schlüssel für die M2M OAuth-Authentifizierung oder die Authentifizierung mit OAuth 2.0-Clientanmeldeinformationen. Geheime Schlüssel der Microsoft Entra ID werden nicht unterstützt.

2. Erstellen Sie ein Azure Databricks-OAuth-Geheimnis für den Dienstprinzipal. Weitere Informationen dazu finden Sie unter Manuelles Generieren und Verwenden von Zugriffstoken für die OAuth-M2M-Authentifizierung.

3. Gewähren Sie dem Dienstprinzipal Zugriff auf Ihren Cluster oder Ihr Warehouse. Weitere Informationen finden Sie unter Compute-Berechtigungen und Verwalten eines SQL-Warehouse.

Fügen Sie die folgenden Eigenschaften zu Ihrer vorhandenen JDBC-Verbindungs-URL oder zu Ihrem java.util.Properties-Objekt hinzu:

Persönliches Zugriffstoken für Azure Databricks

Fügen Sie zur Authentifizierung Ihrer Treiberverbindung mithilfe eines persönlichen Azure Databricks Zugriffstokens die folgenden Eigenschaften zu Ihrer URL der JDBC-Verbindungs-URL oder zum java.util.Properties-Objekt hinzu:

Verbindungseigenschaften

Die folgenden zusätzlichen Verbindungseigenschaften werden vom JDBC-Treiber unterstützt. Bei Eigenschaften wird die Groß-/Kleinschreibung nicht berücksichtigt.

SQL-Konfigurationseigenschaften

Die folgenden SQL-Konfigurationseigenschaften werden vom JDBC-Treiber unterstützt. Diese werden auch unter Konfigurationsparameter beschrieben. Bei Eigenschaften wird die Groß-/Kleinschreibung nicht berücksichtigt.

Protokolleigenschaften

Die folgenden Protokollierungseigenschaften werden vom JDBC-Treiber unterstützt. Bei Eigenschaften wird die Groß-/Kleinschreibung nicht berücksichtigt.

Aktivierung und Konfiguration der Protokollierung

Der ELEMENTTREIBER UNTERSTÜTZT die Simple Logging Facade for Java (SLF4J) und java.util.logging (JUL) -Frameworks. Der Treiber verwendet standardmäßig das JUL-Protokollierungsframework.

So aktivieren und konfigurieren Sie die Protokollierung für den BROWSERtreiber:

1. Aktivieren Sie das Protokollierungsframework, das Sie verwenden möchten:

   • Legen Sie für die SLF4J-Protokollierung die Systemeigenschaft -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER fest, und stellen Sie die SLF4J-Bindungsimplementierung (kompatibel mit SLF4J, Version 2.0.13 und höher) und entsprechende Konfigurationsdatei im Klassenpfad bereit.
   • Legen Sie für die JUL-Protokollierung die Systemeigenschaft -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERfest. Dies ist die Standardeinstellung.

2. Legen Sie die LogLevel Eigenschaft für die Verbindungszeichenfolge auf die gewünschte Informationsebene fest, die in Protokolldateien eingeschlossen werden soll.

3. Legen Sie die LogPath Eigenschaft für die Verbindungszeichenfolge auf den vollständigen Pfad zum Ordner fest, in dem Protokolldateien gespeichert werden sollen.

   Die folgende Verbindungs-URL ermöglicht beispielsweise die Protokollierungsebene 6 und speichert die Protokolldateien im Ordner "C:temp":

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
   

4. Starten Sie Die DATEI -ANWENDUNG NEU, und stellen Sie die Verbindung mit dem Server wieder her, um die Einstellungen anzuwenden.

Beispiel: Ausführen einer Abfrage mithilfe des JDBC-Treibers

Das folgende Beispiel zeigt, wie Sie den JDBC-Treiber verwenden, um eine Databricks-SQL-Abfrage über eine Azure Databricks Computeressource auszuführen.

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();
        }
    }
}

Zusätzliche Ressourcen

• DataGrip-Integration in Azure Databricks

• DBeaver-Integration in Azure Databricks

• Verbinden Sie sich mit SQL Workbench/J

• Verbinden Sie sich mit Infoworks

• Verbinden Sie sich mit Qlik Replicate

• Verbinden Sie sich mit StreamSets

• Verbinden Sie sich mit Syncsort

• Herstellen einer Verbindung mit MicroStrategy