Databricks JDBC-drivrutin (OSS)
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.
- För SLF4J-loggning anger du systemegenskapen
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();
}
}
}