Databricks JDBC-stuurprogramma (OSS)

Artikel
01/22/2025

Belangrijk

Dit stuurprogramma bevindt zich in openbare preview en zal beschikbaar zijn als open source wanneer het algemeen beschikbaar is (GA).

Met Databricks JDBC (OSS), de nieuwste versie van het stuurprogramma, kunt u hulpprogramma's zoals DataGrip, DBeaveren SQL Workbench/J verbinden met Azure Databricks via Java Database Connectivity (JDBC), een industriestandaardspecificatie voor toegang tot databasebeheersystemen.

Dit stuurprogramma heeft de JDBC-API's geïmplementeerd en biedt kernfunctionaliteit, waaronder OAuth, Cloud Fetch en functies zoals volumeopname van Unity Catalog. De systeemeigen querymodus wordt uitgevoerd en biedt ondersteuning voor systeemeigen geparameteriseerde query's en kan worden uitgevoerd met behulp van API's voor instructieuitvoering, die de nuttige bewaarfunctie voor queryresultaten of Thrift biedt.

Dit artikel bevat informatie over het installeren en gebruiken van het Databricks JDBC-stuurprogramma (OSS). Zie Databricks JDBC-stuurprogramma voor meer informatie over het niet-OSS Databricks JDBC-stuurprogramma.

Vereisten

Als u het Databricks JDBC-stuurprogramma (OSS) wilt gebruiken, moet aan de volgende vereisten worden voldaan:

Java Runtime Environment (JRE) 11.0 of hoger. CI-tests worden ondersteund op JRE 11, 17 en 21.

Notitie

Als gevolg van een wijziging in JDK 16 die een compatibiliteitsprobleem heeft veroorzaakt met de Apache Arrow-bibliotheek die door het JDBC-stuurprogramma wordt gebruikt, kunnen runtimefouten optreden bij het gebruik van het JDBC-stuurprogramma met JDK 16 of hoger. Als u deze fouten wilt voorkomen, start u de toepassing of het stuurprogramma opnieuw met behulp van de volgende JVM-opdrachtoptie:

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

Het stuurprogramma installeren

Het Databricks JDBC-stuurprogramma (OSS) wordt gepubliceerd in de Maven-opslagplaats.

U kunt een van de volgende handelingen uitvoeren om het stuurprogramma te installeren:

Voor Maven-projecten voegt u de volgende afhankelijkheid toe aan het bestand van pom.xml het project om Maven te instrueren het JDBC-stuurprogramma automatisch te downloaden met de opgegeven versie:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
Voor Gradle-projecten voegt u de volgende afhankelijkheid toe aan het buildbestand van het project om Gradle te instrueren het JDBC-stuurprogramma automatisch te downloaden met de opgegeven versie:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Zie de Maven-opslagplaatsom de syntaxis van de afhankelijkheid voor andere projecttypen weer te geven en om het meest recente versienummer van het Databricks JDBC-stuurprogramma (OSS) op te halen.

De verbindings-URL configureren

Als u verbinding wilt maken met uw Azure Databricks-werkruimte met behulp van het JDBC-stuurprogramma, moet u een JDBC-verbindings-URL opgeven die verschillende verbindingsinstellingen bevat, zoals de hostnaam van de server van uw Azure Databricks-werkruimte, de instellingen voor de rekenresource en verificatiereferenties om verbinding te maken met de werkruimte.

U kunt de waarde van deze eigenschappen instellen op de JDBC-verbindings-URL, deze instellen en doorgeven aan de methode DriverManager.getConnectionof een combinatie van beide. Raadpleeg de documentatie van de provider voor hoe u het beste verbinding kunt maken met uw specifieke app, client, SDK, API of SQL-hulpprogramma.

De URL van de JDBC-verbinding moet de volgende indeling hebben. Eigenschappen zijn niet hoofdlettergevoelig.

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

U kunt ook de instellingen opgeven met behulp van de java.util.Properties klasse of een combinatie:

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

Verbindings-URL-elementen worden beschreven in de volgende tabel. Zie de onderstaande secties voor meer informatie over aanvullende eigenschappen, waaronder verificatie-eigenschappen. URL-elementen en -eigenschappen zijn niet hoofdlettergevoelig.

URL-element of -eigenschap	Beschrijving
`<server-hostname>`	De hostnaamwaarde van de serverhostnaam van de Azure Databricks-rekenresource.
`<port>`	De poortwaarde van de Azure Databricks-rekenresource. De standaardwaarde is `443`.
`<schema>`	De naam van het schema. U kunt ook de eigenschap `ConnSchema` instellen. Zie verbindingseigenschappen.
`httpPath`	De HTTP-padwaarde van de Azure Databricks-rekenresource. De connector vormt het HTTP-adres waarmee verbinding moet worden gemaakt door de `httpPath` waarde toe te voegen aan de host en poort die is opgegeven in de verbindings-URL. Als u bijvoorbeeld verbinding wilt maken met het HTTP-adres `http://localhost:10002/cliservice`, gebruikt u de volgende verbindings-URL: `jdbc:databricks://localhost:10002;httpPath=cliservice`

De JDBC-verbinding URL ophalen voor een Azure Databricks cluster.

Meld u aan bij uw Azure Databricks-werkruimte.
Klik in de zijbalk op Compute en klik vervolgens op de naam van het doelcluster.
Vouw op het tabblad Configuratie geavanceerde opties uit.
Klik op het tabblad JDBC/ODBC .
Kopieer de JDBC-URL om te gebruiken als de JDBC-verbindings-URL of maak de URL op basis van waarden in de hostnaam van de server, poorten http-pad velden.

De JDBC-verbindings-URL voor een Databricks SQL warehouse ophalen:

Meld u aan bij uw Azure Databricks-werkruimte.
Klik in de zijbalk op SQL Warehouses en klik vervolgens op de naam van het doelwarehouse.
Klik op het tabblad Verbindingsgegevens .
Kopieer de JDBC-URL om te gebruiken als de JDBC-verbindings-URL of maak de URL op basis van waarden in de hostnaam van de server, poorten http-pad velden.

Het stuurprogramma verifiëren

U kunt de verbinding met het JDBC-stuurprogramma verifiëren met behulp van een van de volgende verificatiemechanismen:

OAuth-verificatie van gebruiker naar machine (U2M) (aanbevolen)
OAuth-verificatie van machine-naar-machine (M2M)
Persoonlijk toegangstoken van Azure Databricks

OAuth-verificatie van gebruiker naar machine (U2M)

Het JDBC-stuurprogramma ondersteunt OAuth-gebruikers-naar-machine-verificatie (U2M) voor realtime menselijke aanmelding en toestemming om het databricks-doelgebruikersaccount te verifiëren. Dit wordt ook wel OAuth-verificatie op basis van een browser genoemd.

Azure Databricks heeft de OAuth-client-id databricks-sql-jdbc voor klanten gemaakt. Dit is ook de standaard-OAuth-client-id die wordt gebruikt in het JDBC-stuurprogramma. Als u OAuth U2M-verificatie wilt configureren, voegt u de volgende eigenschappen toe aan uw bestaande JDBC-verbindings-URL of java.util.Properties -object:

Eigenschappen	Weergegeven als
`AuthMech`	`11`
`Auth_Flow`	`2`

OAuth-verificatie van machine-naar-machine (M2M)

Het JDBC-stuurprogramma ondersteunt OAuth-M2M-verificatie (machine-to-machine) met behulp van een Azure Databricks-service-principal. Dit wordt ook wel OAuth 2.0 client credentials verificatie genoemd. Zie Toegang zonder toezicht autoriseren tot Azure Databricks-resources met een service-principal met behulp van OAuth.

Verificatie van OAuth M2M- of OAuth 2.0-clientreferenties configureren:

Maak een door Microsoft Entra ID beheerde service-principal en wijs deze vervolgens toe aan Azure Databricks-accounts en -werkruimten. Zie Service-principals beheren voor meer informatie.

Belangrijk

Het Databricks JDBC-stuurprogramma (OSS) ondersteunt authenticatie met Azure Databricks OAuth-geheimen voor OAuth M2M of OAuth 2.0-clientreferenties. Microsoft Entra ID-geheimen worden niet ondersteund.
Maak een Azure Databricks OAuth-geheim voor de service-principal. Zie hiervoor Handmatig toegangstokens genereren en gebruiken voor de authenticatie van OAuth-serviceprincipals.
Geef de service-principal toegang tot uw cluster of magazijn. Zie Compute-machtigingen of een SQL-warehouse beheren.

Voeg de volgende eigenschappen toe aan uw bestaande JDBC-verbindings-URL of java.util.Properties -object:

Eigenschappen	Weergegeven als
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	De waarde van de toepassings-id (client) van de service-principal.
`OAuth2Secret`	Het Azure Databricks OAuth-geheim van de service-principal. (Microsoft Entra ID-geheimen worden niet ondersteund voor verificatie van OAuth M2M- of OAuth 2.0-clientreferenties.)

Persoonlijk toegangstoken van Azure Databricks

Als u uw JDBC-stuurprogrammaverbinding wilt verifiëren met behulp van een persoonlijk toegangstoken van Azure Databricks, voegt u de volgende eigenschappen toe aan uw JDBC-verbindings-URL of java.util.Properties -object:

Eigenschappen	Weergegeven als
`AuthMech`	`3`
`user`	De waarde `token`, als een tekenreeks.
`PWD` of `password`	Uw persoonlijke toegangstokenwaarde van Azure Databricks als een tekenreeks.

Verbindingseigenschappen

De volgende aanvullende verbindingseigenschappen worden ondersteund door het JDBC-stuurprogramma. Eigenschappen zijn niet hoofdlettergevoelig.

Eigenschappen	Default value	Beschrijving
`AuthMech`	Vereist	Het verificatiemechanisme, waarbij `3` het mechanisme opgeeft, is een persoonlijk toegangstoken van Azure Databricks en `11` geeft aan dat het mechanisme OAuth 2.0-tokens is. Er zijn extra eigenschappen vereist voor elk mechanisme. Zie Het stuurprogramma verifiëren.
`Auth_Flow`	`0`	De OAuth2-verificatiestroom voor de stuurprogrammaverbinding. Deze eigenschap is vereist als `AuthMech` dit is `11`.
`SSL`	`1`	Of de connector met de Spark-server communiceert via een socket met SSL.
`ConnCatalog` of `catalog`	`SPARK`	De naam van de standaardcatalogus die moet worden gebruikt.
`ConnSchema` of `schema`	`default`	De naam van het standaardschema dat moet worden gebruikt. Dit kan worden opgegeven door `<schema>` in de URL te vervangen door de naam van het schema dat moet worden gebruikt of door de eigenschap `ConnSchema` in te stellen op de naam van het schema dat moet worden gebruikt.
`ProxyAuth`	`0`	Als dit is ingesteld op `1`, gebruikt het stuurprogramma de proxyverificatiegebruiker en het wachtwoord, vertegenwoordigd door `ProxyUID` en `ProxyPwd`.
`ProxyHost`	`null`	Een tekenreeks die de naam vertegenwoordigt van de proxyhost die moet worden gebruikt wanneer `UseProxy` ook is ingesteld op `1`.
`ProxyPort`	`null`	Een geheel getal dat het nummer aangeeft van de proxypoort die moet worden gebruikt wanneer `UseProxy` ook is ingesteld op `1`.
`ProxyUID`	`null`	Een tekenreeks die de gebruikersnaam vertegenwoordigt die moet worden gebruikt voor proxyverificatie wanneer `ProxyAuth` en `UseProxy` ook zijn ingesteld op `1`.
`ProxyPwd`	`null`	Een tekenreeks die het wachtwoord vertegenwoordigt dat moet worden gebruikt voor proxyverificatie wanneer `ProxyAuth` en `UseProxy` ook zijn ingesteld op `1`.
`UseProxy`	`0`	Als dit is ingesteld op `1`, gebruikt het stuurprogramma de opgegeven proxyinstellingen (bijvoorbeeld: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`en `ProxyUID`).
`UseSystemProxy`	`0`	Als dit is ingesteld op `1`, gebruikt het stuurprogramma de proxy-instellingen die zijn ingesteld op systeemniveau. Als er extra proxy-eigenschappen zijn ingesteld in de verbindings-URL, overschrijven deze aanvullende proxy-eigenschappen die zijn ingesteld op systeemniveau.
`UseCFProxy`	`0`	Als dit is ingesteld op `1`, gebruikt het stuurprogramma de proxy-instellingen voor het ophalen van de cloud als deze zijn opgegeven, anders gebruikt u de reguliere proxy.
`CFProxyAuth`	`0`	Als dit is ingesteld op `1`, gebruikt het stuurprogramma de proxyverificatiegebruiker en het wachtwoord, vertegenwoordigd door `CFProxyUID` en `CFProxyPwd`.
`CFProxyHost`	`null`	Een tekenreeks die de naam vertegenwoordigt van de proxyhost die moet worden gebruikt wanneer `UseCFProxy` ook is ingesteld op `1`.
`CFProxyPort`	`null`	Een geheel getal dat het nummer aangeeft van de proxypoort die moet worden gebruikt wanneer `UseCFProxy` ook is ingesteld op `1`.
`CFProxyUID`	`null`	Een tekenreeks die de gebruikersnaam vertegenwoordigt die moet worden gebruikt voor proxyverificatie wanneer `CFProxyAuth` en `UseCFProxy` ook zijn ingesteld op `1`.
`CFProxyPwd`	`null`	Een tekenreeks die het wachtwoord vertegenwoordigt dat moet worden gebruikt voor proxyverificatie wanneer `CFProxyAuth` en `UseCFProxy` ook zijn ingesteld op `1`.
`AsyncExecPollInterval`	`200`	De tijd in milliseconden tussen elke poll voor de asynchrone uitvoeringsstatus van de query. Asynchroon verwijst naar het feit dat de RPC-aanroep die wordt gebruikt om een query uit te voeren op Spark asynchroon is. Dit betekent niet dat Asynchrone JDBC-bewerkingen worden ondersteund.
`UserAgentEntry`	`browser`	De vermelding User-Agent die moet worden opgenomen in de HTTP-aanvraag. Deze waarde heeft de volgende indeling: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Of het JDBC-stuurprogramma de Thrift-client moet gebruiken om verbinding te maken met een cluster voor alle doeleinden. De standaardwaarde werkt voor SQL-warehouses.

SQL-configuratie-eigenschappen

De volgende SQL-configuratie-eigenschappen worden ondersteund door het JDBC-stuurprogramma. Deze worden ook beschreven in Configuratieparameters. Eigenschappen zijn niet hoofdlettergevoelig.

Eigenschappen	Default value	Beschrijving
`ansi_mode`	`TRUE`	Of u strikte ANSI SQL-gedrag wilt inschakelen voor bepaalde functies en cast-regels.
`enable_photon`	`TRUE`	Hiermee wordt aangegeven of de photon vectorized query-engine moet worden ingeschakeld.
`legacy_time_parser_policy`	`EXCEPTION`	De methoden voor het parseren en opmaken van datums en tijdstempels. Geldige waarden zijn `EXCEPTION`, `LEGACY`en `CORRECTED`.
`max_file_partition_bytes`	`128m`	Het maximum aantal bytes dat moet worden ingepakt in één partitie bij het lezen van bronnen op basis van bestanden. De instelling kan elk positief geheel getal zijn en eventueel een meting zoals `b` (bytes) `k` of `kb` (1024 bytes) bevatten.
`read_only_external_metastore`	`false`	Hiermee bepaalt u of een externe metastore wordt behandeld als alleen-lezen.
`statement_timeout`	`172800`	Hiermee stelt u een time-out voor de SQL-instructie in tussen 0 en 172800 seconden.
`timezone`	`UTC`	Stel de lokale tijdzone in. Regio-id's in de vorm `area/city`, zoals Amerika/Los_Angeles of zone-offsets in de notatie (+\|-)HH, (+\|-)HH:mm of (+\|-)HH:mm:ss, bijvoorbeeld -08, +01:00 of -13:33:33. `UTC` Wordt ook ondersteund als alias voor +00:00
`use_cached_result`	`true`	Of Databricks SQL resultaten indien mogelijk in de cache opgeslagen en hergebruikt.

Eigenschappen van logboekregistratie

De volgende eigenschappen voor logboekregistratie worden ondersteund door het JDBC-stuurprogramma. Eigenschappen zijn niet hoofdlettergevoelig.

Eigenschappen	Default value	Beschrijving
`LogLevel`	`OFF`	Het logboekregistratieniveau, een waarde 0 tot en met 6: - 0: Alle logboekregistratie uitschakelen. - 1: Schakel logboekregistratie in op het FATAL-niveau, waarmee zeer ernstige foutgebeurtenissen worden geregistreerd die ertoe leiden dat de connector wordt afgebroken. - 2: Schakel logboekregistratie in op foutniveau, waarmee foutgebeurtenissen worden geregistreerd waardoor de connector mogelijk nog steeds wordt uitgevoerd. - 3: Schakel logboekregistratie in op waarschuwingsniveau, waarmee gebeurtenissen worden geregistreerd die kunnen leiden tot een fout als er geen actie wordt ondernomen. - 4: Schakel logboekregistratie in op het INFO-niveau, waarin algemene informatie wordt beschreven waarin de voortgang van de connector wordt beschreven. - 5: Schakel logboekregistratie in op het niveau DEBUG, waarmee gedetailleerde informatie wordt beschreven die nuttig is voor het opsporen van fouten in de connector. - 6: Schakel logboekregistratie in op traceringsniveau, waarmee alle activiteit van de connector wordt in logboeken opgeslagen. Gebruik deze eigenschap om logboekregistratie in of uit te schakelen in de connector en om de hoeveelheid details op te geven die is opgenomen in logboekbestanden.
`LogPath`	Om het standaardpad voor logboeken te bepalen, gebruikt het stuurprogramma de waarde die is ingesteld voor deze systeemeigenschappen, in deze prioriteitsvolgorde: 1. `user.dir` 2. `java.io.tmpdir` 3. de huidige map, met andere woorden `.`	Het volledige pad naar de map waarin de connector logboekbestanden opslaat wanneer logging is ingeschakeld, als een tekenreeks. Om ervoor te zorgen dat de verbindings-URL compatibel is met alle JDBC-toepassingen, escapet u de backslashes (`\`) in het bestandspad door een andere backslash te typen. Als de `LogPath` waarde ongeldig is, verzendt de connector de vastgelegde gegevens naar de standaarduitvoerstroom (System.out).
`LogFileSize`	Geen maximum	De maximaal toegestane logboekbestandsgrootte, opgegeven in MB
`LogFileCount`	Geen maximum	Het maximum aantal toegestane logboekbestanden

Logboekregistratie inschakelen en configureren

Het JDBC-stuurprogramma ondersteunt de Frameworks Simple Logging Facade voor Java (SLF4J) en java.util.logging (JUL). Het stuurprogramma maakt standaard gebruik van het JUL-logboekregistratieframework.

Logboekregistratie inschakelen en configureren voor het JDBC-stuurprogramma:

Schakel het framework voor logboekregistratie in dat u wilt gebruiken:
- Voor SLF4J-logboekregistratie stelt u de systeemeigenschap in -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER en geeft u de SLF4J-binding-implementatie op (compatibel met SLF4J versie 2.0.13 en hoger) en het bijbehorende configuratiebestand in het klassepad.
- Stel voor JUL-logboekregistratie de systeemeigenschap in -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Dit is de standaardinstelling.
Stel de eigenschap LogLevel van de verbindingsreeks in op het gewenste informatieniveau dat moet worden opgenomen in logboekbestanden.
Stel de eigenschap LogPath op de verbindingsreeks in op het volledige pad naar de map waarin u logboekbestanden wilt opslaan.

Met de volgende verbindings-URL kunt u bijvoorbeeld logboekregistratieniveau 6 inschakelen en worden de logboekbestanden opgeslagen in de map C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Start de JDBC-toepassing opnieuw op en maak opnieuw verbinding met de server om de instellingen toe te passen.

Voorbeeld: Een query uitvoeren met behulp van het JDBC-stuurprogramma

In het volgende voorbeeld ziet u hoe u het JDBC-stuurprogramma gebruikt om een Databricks SQL-query uit te voeren met behulp van een Azure Databricks-rekenresource.

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

Delen via