Databricks JDBC-drivrutin (OSS)

Artikel
01/17/2025

Viktigt!

Den här drivrutinen finns i offentlig förhandsversion och kommer att vara tillgänglig som öppen källkod när den blir allmänt tillgänglig (GA).

Med Databricks JDBC (OSS), den senaste versionen av drivrutinen, kan du ansluta verktyg som DataGrip, DBeaveroch SQL Workbench/J till Azure Databricks via Java Database Connectivity (JDBC), en branschstandardspecifikation för åtkomst till databashanteringssystem.

Den här drivrutinen har implementerat JDBC-API:erna och tillhandahåller grundläggande funktioner som OAuth, Cloud Fetch och funktioner som volyminmatning i Unity Catalog. Den kör inbyggt frågeläge och stöder intern parameteriserad fråga och kan köras med api:er för körning av instruktioner, vilket ger den fördelaktiga funktionen för kvarhållning av frågeresultat eller Thrift.

Den här artikeln innehåller information om hur du installerar och använder Databricks JDBC-drivrutinen (OSS). Information om JDBC-drivrutinen för icke-OSS Databricks finns i Databricks JDBC-drivrutin.

Krav

Om du vill använda Databricks JDBC-drivrutinen (OSS) måste följande krav uppfyllas:

Java Runtime Environment (JRE) 11.0 eller senare. CI-testning stöds på JRE 11, 17 och 21.

Kommentar

Som ett resultat av en ändring i JDK 16 som orsakade ett kompatibilitetsproblem med Apache Arrow-biblioteket som används av JDBC-drivrutinen, kan körningsfel uppstå när du använder JDBC-drivrutinen med JDK 16 eller senare. Om du vill förhindra dessa fel startar du om programmet eller drivrutinen med hjälp av följande JVM-kommandoalternativ:

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

Installera drivrutinen

Databricks JDBC-drivrutinen (OSS) publiceras på Maven-lagringsplatsen.

Om du vill installera drivrutinen kan du göra något av följande:

För Maven-projekt lägger du till följande beroende i projektets pom.xml fil för att instruera Maven att automatiskt ladda ned JDBC-drivrutinen med den angivna versionen:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
För Gradle-projekt lägger du till följande beroende i projektets byggfil för att instruera Gradle att automatiskt ladda ned JDBC-drivrutinen med den angivna versionen:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Information om hur du visar beroendesyntaxen för andra projekttyper och för att hämta det senaste versionsnumret för Databricks JDBC-drivrutinen (OSS) finns i Maven-lagringsplatsen.

Konfigurera anslutnings-URL:en

För att ansluta till din Azure Databricks-arbetsyta med JDBC-drivrutinen måste du ange en JDBC-anslutnings-URL som innehåller olika anslutningsinställningar, till exempel servervärdnamnet för din Azure Databricks-arbetsyta, inställningarna för beräkningsresurser och autentiseringsuppgifter för att ansluta till arbetsytan.

Du kan ange värdet för de här egenskaperna på JDBC-anslutnings-URL:en, ange och skicka dem till metoden DriverManager.getConnection eller en kombination av båda. Se leverantörens dokumentation för hur du bäst ansluter med din specifika app, klient, SDK, API eller SQL-verktyg.

JDBC-anslutnings-URL:en måste ha följande format. Egenskaper är skiftlägesokänsliga.

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

Du kan också ange inställningarna med hjälp av java.util.Properties klassen eller en kombination:

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

Anslutnings-URL-element beskrivs i följande tabell. Information om ytterligare egenskaper, inklusive autentiseringsegenskaper, finns i avsnitten nedan. URL-element och egenskaper är skiftlägesokänsliga.

URL-element eller egenskap	beskrivning
`<server-hostname>`	Azure Databricks-beräkningsresursens värdnamnsvärde för servern.
`<port>`	Azure Databricks-beräkningsresursens portvärde. Standardvärdet är `443`.
`<schema>`	Namnet på schemat. Du kan också ange egenskapen `ConnSchema` . Se Anslutningsegenskaper.
`httpPath`	Azure Databricks-beräkningsresursens HTTP-sökvägsvärde. Anslutningsappen utgör DEN HTTP-adress som ska anslutas till genom `httpPath` att lägga till värdet på värden och porten som anges i anslutnings-URL:en. Om du till exempel vill ansluta till HTTP-adressen `http://localhost:10002/cliservice`använder du följande anslutnings-URL: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Hämta JDBC-anslutnings-URL:en för ett Azure Databricks-kluster:

Logga in på Azure Databricks-arbetsytan.
I sidofältet klickar du på Beräkning och sedan på målklustrets namn.
På fliken Konfiguration expanderar du Avancerade alternativ.
Klicka på fliken JDBC/ODBC .
Kopiera JDBC-URL:en som ska användas som JDBC-anslutnings-URL eller konstruera URL:en från värden i fälten Servervärdnamn, Port och HTTP-sökväg.

Hämta JDBC-anslutnings-URL:en för ett Databricks SQL-lager:

Logga in på Azure Databricks-arbetsytan.
I sidofältet klickar du på SQL Warehouses och sedan på mållagrets namn.
Klicka på fliken Anslutningsinformation .
Kopiera JDBC-URL:en som ska användas som JDBC-anslutnings-URL eller konstruera URL:en från värden i fälten Servervärdnamn, Port och HTTP-sökväg.

Autentisera drivrutinen

Du kan autentisera JDBC-drivrutinsanslutningen med någon av följande autentiseringsmekanismer:

OAuth-autentisering från användare till dator (U2M) (rekommenderas)
OAuth-autentisering från dator till dator (M2M)
Personlig åtkomsttoken för Azure Databricks

OAuth-autentisering från användare till dator (U2M)

JDBC-drivrutinen stöder OAuth-autentisering från användare till dator (U2M) för mänsklig inloggning i realtid och medgivande för att autentisera databricks-målanvändarkontot. Detta kallas även webbläsarbaserad OAuth-autentisering.

Azure Databricks har skapat OAuth-klient-ID databricks-sql-jdbc för kunder. Detta är också standard-OAuth-klient-ID som används i JDBC-drivrutinen. Om du vill konfigurera OAuth U2M-autentisering lägger du bara till följande egenskaper i din befintliga JDBC-anslutnings-URL eller java.util.Properties -objekt:

Property	Värde
`AuthMech`	`11`
`Auth_Flow`	`2`

OAuth-autentisering från dator till dator (M2M)

JDBC-drivrutinen stöder OAuth-M2M-autentisering (machine-to-machine) med hjälp av ett huvudnamn för Azure Databricks-tjänsten. Detta kallas även OAuth 2.0-klientautentiseringsuppgifter. Se Auktorisera obevakad åtkomst till Azure Databricks-resurser med ett tjänstehuvud med OAuth.

Så här konfigurerar du autentiseringsuppgifter för OAuth M2M- eller OAuth 2.0-klienten:

Skapa ett Microsoft Entra ID-hanterat tjänsthuvudnamn och tilldela det sedan till Azure Databricks-konton och arbetsytor. Mer information finns i Hantera tjänstens huvudnamn.

Viktigt!

Databricks JDBC Driver (OSS) stöder Azure Databricks OAuth-hemligheter för OAuth M2M- eller OAuth 2.0-klientautentiseringsuppgifter. Microsoft Entra-ID-hemligheter stöds inte.
Skapa en Azure Databricks OAuth-hemlighet för tjänstens huvudnamn. Det gör du genom att läsa Generera och använda åtkomsttoken manuellt för OAuth-tjänstens huvudnamnsautentisering.
Ge tjänstens huvudnamn åtkomst till klustret eller informationslagret. Se Beräkningsbehörigheter eller Hantera ett SQL-lager.

Lägg till följande egenskaper i din befintliga JDBC-anslutnings-URL eller java.util.Properties -objekt:

Property	Värde
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	Tjänstens huvudnamns program-ID (klient)-värde.
`OAuth2Secret`	Tjänstens huvudnamns Azure Databricks OAuth-hemlighet. (Microsoft Entra ID-hemligheter stöds inte för OAuth M2M- eller OAuth 2.0-klientautentiseringsuppgifter.)

Personlig åtkomsttoken för Azure Databricks

Om du vill autentisera din JDBC-drivrutinsanslutning med en personlig åtkomsttoken för Azure Databricks lägger du till följande egenskaper i JDBC-anslutnings-URL:en eller java.util.Properties -objektet:

Property	Värde
`AuthMech`	`3`
`user`	Värdet `token`, som en sträng.
`PWD` eller `password`	Ditt personliga åtkomsttokenvärde för Azure Databricks som en sträng.

Anslutningsegenskaper

Följande ytterligare anslutningsegenskaper stöds av JDBC-drivrutinen. Egenskaper är skiftlägesokänsliga.

Property	Standardvärde	beskrivning
`AuthMech`	Obligatoriskt	Autentiseringsmekanismen, där `3` anger att mekanismen är en personlig åtkomsttoken för Azure Databricks, och `11` anger att mekanismen är OAuth 2.0-token. Ytterligare egenskaper krävs för varje mekanism. Se Autentisera drivrutinen.
`Auth_Flow`	`0`	OAuth2-autentiseringsflödet för drivrutinsanslutningen. Den här egenskapen krävs om `AuthMech` är `11`.
`SSL`	`1`	Om anslutningsappen kommunicerar med Spark-servern via en SSL-aktiverad socket.
`ConnCatalog` eller `catalog`	`SPARK`	Namnet på den standardkatalog som ska användas.
`ConnSchema` eller `schema`	`default`	Namnet på det standardschema som ska användas. Detta kan anges antingen genom att `<schema>` ersätta i URL:en med namnet på schemat som ska användas eller genom att ställa in `ConnSchema` egenskapen på namnet på schemat som ska användas.
`ProxyAuth`	`0`	Om den är inställd `1`på använder drivrutinen proxyautentiseringsanvändaren och lösenordet, som representeras av `ProxyUID` och `ProxyPwd`.
`ProxyHost`	`null`	En sträng som representerar namnet på proxyvärden som ska användas när `UseProxy` är också inställt på `1`.
`ProxyPort`	`null`	Ett heltal som representerar antalet proxyportar som ska användas när `UseProxy` är också inställt på `1`.
`ProxyUID`	`null`	En sträng som representerar användarnamnet som ska användas för proxyautentisering när `ProxyAuth` och `UseProxy` är också inställt på `1`.
`ProxyPwd`	`null`	En sträng som representerar lösenordet som ska användas för proxyautentisering när `ProxyAuth` och `UseProxy` är också inställt på `1`.
`UseProxy`	`0`	Om inställningen är inställd `1`på använder drivrutinen de angivna proxyinställningarna (till exempel: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`och `ProxyUID`).
`UseSystemProxy`	`0`	Om inställningen är inställd `1`på använder drivrutinen de proxyinställningar som har angetts på systemnivå. Om ytterligare proxyegenskaper anges i anslutnings-URL:en åsidosätter dessa ytterligare proxyegenskaper de som har angetts på systemnivå.
`UseCFProxy`	`0`	Om inställningen är inställd `1`på använder drivrutinen proxyinställningarna för molnhämtning om de tillhandahålls, annars använder du den vanliga proxyn.
`CFProxyAuth`	`0`	Om den är inställd `1`på använder drivrutinen proxyautentiseringsanvändaren och lösenordet, som representeras av `CFProxyUID` och `CFProxyPwd`.
`CFProxyHost`	`null`	En sträng som representerar namnet på proxyvärden som ska användas när `UseCFProxy` är också inställt på `1`.
`CFProxyPort`	`null`	Ett heltal som representerar antalet proxyportar som ska användas när `UseCFProxy` är också inställt på `1`.
`CFProxyUID`	`null`	En sträng som representerar användarnamnet som ska användas för proxyautentisering när `CFProxyAuth` och `UseCFProxy` är också inställt på `1`.
`CFProxyPwd`	`null`	En sträng som representerar lösenordet som ska användas för proxyautentisering när `CFProxyAuth` och `UseCFProxy` är också inställt på `1`.
`AsyncExecPollInterval`	`200`	Tiden i millisekunder mellan varje avsökning för den asynkrona frågekörningsstatusen. Asynkront refererar till det faktum att RPC-anropet som används för att köra en fråga mot Spark är asynkront. Det betyder inte att JDBC-asynkrona åtgärder stöds.
`UserAgentEntry`	`browser`	Posten User-Agent som ska ingå i HTTP-begäran. Det här värdet är i följande format: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Om JDBC-drivrutinen ska använda Thrift-klienten för att ansluta till ett kluster för alla syften. Standardvärdet fungerar för SQL-lager.

SQL-konfigurationsegenskaper

Följande SQL-konfigurationsegenskaper stöds av JDBC-drivrutinen. Dessa beskrivs också i Konfigurationsparametrar. Egenskaper är skiftlägesokänsliga.

Property	Standardvärde	beskrivning
`ansi_mode`	`TRUE`	Om du vill aktivera strikt ANSI SQL-beteende för vissa funktioner och regler för gjutning.
`enable_photon`	`TRUE`	Om du vill aktivera den fotovektoriserade frågemotorn.
`legacy_time_parser_policy`	`EXCEPTION`	De metoder som används för att parsa och formatera datum och tidsstämplar. Giltiga värden är `EXCEPTION`, `LEGACY` och `CORRECTED`.
`max_file_partition_bytes`	`128m`	Det maximala antalet byte som ska packas i en enda partition när du läser från filbaserade källor. Inställningen kan vara ett positivt heltal och eventuellt inkludera ett mått som `b` (byte) `k` eller `kb` (1 024 byte).
`read_only_external_metastore`	`false`	Styr om ett externt metaarkiv behandlas som skrivskyddat.
`statement_timeout`	`172800`	Anger tidsgränsen för SQL-instruktionen mellan 0 och 172800 sekunder.
`timezone`	`UTC`	Ange den lokala tidszonen. Region-ID:n i formatet `area/city`, till exempel Amerika/Los_Angeles eller zonförskjutningar i formatet (+\|-)HH, (+\|-)HH:mm eller (+\|-)HH:mm:ss, t.ex. -08, +01:00 eller -13:33:33. `UTC` Dessutom stöds som ett alias för +00:00
`use_cached_result`	`true`	Om Databricks SQL cachelagrar och återanvänder resultat när det är möjligt.

Loggningsegenskaper

Följande loggningsegenskaper stöds av JDBC-drivrutinen. Egenskaper är skiftlägesokänsliga.

Property	Standardvärde	beskrivning
`LogLevel`	`OFF`	Loggningsnivån, som är värdet 0 till 6: - 0: Inaktivera all loggning. – 1: Aktivera loggning på fatal-nivån, som loggar mycket allvarliga felhändelser som leder till att anslutningsappen avbryts. – 2: Aktivera loggning på felnivån, som loggar felhändelser som fortfarande kan tillåta att anslutningsappen fortsätter att köras. - 3: Aktivera loggning på VARNING-nivån, som loggar händelser som kan resultera i ett fel om åtgärden inte vidtas. – 4: Aktivera loggning på INFO-nivån, som loggar allmän information som beskriver förloppet för anslutningsappen. – 5: Aktivera loggning på FELSÖKNINGsnivå, som loggar detaljerad information som är användbar för felsökning av anslutningsappen. – 6: Aktivera loggning på TRACE-nivån, som loggar all anslutningsaktivitet. Använd den här egenskapen för att aktivera eller inaktivera loggning i anslutningsappen och för att ange hur mycket information som ingår i loggfilerna.
`LogPath`	För att fastställa standardsökvägen för loggar använder drivrutinen värdet som angetts för dessa systemegenskaper i den här prioritetsordningen: 1. `user.dir` 2. `java.io.tmpdir` 3. den aktuella katalogen, med andra ord `.`	Den fullständiga sökvägen till mappen där anslutningsappen sparar loggfiler när loggning är aktiverad, som en sträng. För att säkerställa att anslutnings-URL:en är kompatibel med alla JDBC-program kan du undvika omvänt snedstreck (`\`) i filsökvägen genom att skriva ett annat omvänt snedstreck. Om värdet `LogPath` är ogiltigt skickar anslutningsappen den loggade informationen till standardutdataströmmen (System.out).
`LogFileSize`	Inget maxvärde	Den maximala tillåtna loggfilsstorleken som anges i MB
`LogFileCount`	Inget maxvärde	Maximalt antal tillåtna loggfiler

Aktivera och konfigurera loggning

JDBC-drivrutinen stöder ramverken Simple Logging Facade for Java (SLF4J) och java.util.logging (JUL). Drivrutinen använder JUL-loggningsramverket som standard.

Så här aktiverar och konfigurerar du loggning för JDBC-drivrutinen:

Aktivera det loggningsramverk som du vill använda:
- För SLF4J-loggning anger du systemegenskapen -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER och tillhandahåller SLF4J-bindningsimplementeringen (kompatibel med SLF4J version 2.0.13 och senare) och motsvarande konfigurationsfil i klassökvägen.
- För JUL-loggning anger du systemegenskapen -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Det här är standardinställningen.
Ange egenskapen LogLevel på anslutningssträng till önskad informationsnivå som ska ingå i loggfilerna.
LogPath Ange egenskapen på anslutningssträng till den fullständiga sökvägen till mappen där du vill spara loggfiler.

Följande anslutnings-URL aktiverar till exempel loggningsnivå 6 och sparar loggfilerna i mappen C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Starta om JDBC-programmet och återanslut till servern för att tillämpa inställningarna.

Exempel: Kör en fråga med JDBC-drivrutinen

I följande exempel visas hur du använder JDBC-drivrutinen för att köra en Databricks SQL-fråga med hjälp av en Azure Databricks-beräkningsresurs.

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

Dela via