JDBC-anslutning

Anmärkning

Den här funktionen finns i Offentlig förhandsversion för Databricks Runtime 18.1 och DBSQL 2025.40 och senare. För SQL-lager måste du också välja Aktivera nätverk för isolerade arbetsbelastningar i förhandsversionen av Serverlösa SQL Warehouses .

Azure Databricks stöder anslutning till externa databaser med JDBC. Du kan använda en JDBC Unity Catalog-anslutning för att läsa och skriva till en datakälla med Spark Data Source API eller Azure Databricks Remote Query SQL API. JDBC-anslutningen är ett skyddsbart objekt i Unity Catalog som anger JDBC-drivrutinen, URL-sökvägen och autentiseringsuppgifterna för åtkomst till en extern databas. JDBC-anslutningen stöds för Unity Catalogs beräkningstyper, inklusive serverlösa alternativ, standardkluster, dedikerade kluster och Databricks SQL.

Fördelar med att använda en JDBC-anslutning

Läsa och skriva till datakällor med JDBC med Spark Data Source-API:et.
Läs från datakällor med JDBC med hjälp av SQL API:et för fjärrfrågor.
Styrd åtkomst till datakällan med hjälp av en Anslutning till Unity Catalog.
Skapa anslutningen en gång och återanvänd den i alla Unity Catalog-beräkningar.
Stabil för Spark- och beräkningsuppgraderingar.
Autentiseringsuppgifterna för anslutningen är dolda för den frågande användaren.

JDBC jämfört med frågefederation

JDBC kompletterar query federation. Databricks rekommenderar att du väljer frågefederation av följande skäl:

Frågeintegration tillhandahåller finkorniga åtkomstkontroller och styrning på tabellnivå med hjälp av en extern katalog. JDBC Unity Catalog-anslutning ger endast styrning på anslutningsnivå.
Fråge-federation optimerar Spark-frågor för optimal frågeprestanda.

Anmärkning

Frågefederation stöder många populära databaser, inklusive Oracle, MySQL, PostgreSQL, SQL Server och Snowflake. Om databasen stöds rekommenderar Databricks att du använder frågefederation i stället för en JDBC-anslutning. Se Lakehouse Federation för den fullständiga listan över databaser som stöds.

Välj dock att använda en JDBC Unity Catalog-anslutning i följande scenarier:

Din databas innehar inte stöd för frågefederering.
Du vill använda en specifik JDBC-drivrutin.
Du måste skriva till datakällan med Spark (frågefederationen stöder inte skrivningar).
Du behöver mer flexibilitet, prestanda och parallelliseringskontroll via API-alternativ för Spark Data Source.
Du vill skjuta ned SQL-frågor till källan med Spark-alternativet query.

Varför ska du använda JDBC jämfört med PySpark-datakällor?

PySpark-datakällor är ett alternativ till JDBC Spark-datakällan.

Använd en JDBC-anslutning:

Om du vill använda det inbyggda Spark JDBC-stödet.
Om du vill använda en out-of-the-box JDBC-drivrutin som redan finns.
Om du behöver styrning av Unity-katalogen på anslutningsnivå.
Om du vill ansluta från en Unity Catalog-beräkningstyp: serverlös, standard, dedikerad, SQL API.
Om du vill använda din anslutning med Python-, Scala- och SQL-API:er.

Använd en PySpark-datakälla:

Om du vill ha flexibiliteten att utveckla och utforma din Spark-datakälla eller datamottagare med hjälp av Python.
Om du bara använder den i anteckningsböcker eller PySpark-arbetsuppgifter.
Om du vill implementera anpassad partitioneringslogik.

Varken JDBC- eller PySpark-datakällor exponerar statistik för frågeoptimeraren för att välja ordning på åtgärder.

Så här fungerar det

Om du vill ansluta till en datakälla med en JDBC-anslutning installerar du JDBC-drivrutinen på Spark-beräkning. Med anslutningen kan du ange och installera JDBC-drivrutinen i en isolerad sandbox-miljö som är tillgänglig för beräkning med Spark för att säkerställa Sparks säkerhet och styrning av Unity Catalog. Mer information om sandboxing finns i Hur tillämpar Databricks användarisolering?.

Innan du börjar

Om du vill använda en JDBC-anslutning med Spark Data Source API på serverlösa och standardkluster måste du först uppfylla följande krav:

Krav för arbetsyta:

En Azure Databricks-arbetsyta aktiverad för Unity Catalog

Beräkningskrav:

Nätverksanslutning från beräkningsresursen till måldatabassystemet. Se Nätverksanslutning.
Azure Databricks-beräkning måste använda serverlös eller Databricks Runtime 17.3 LTS eller senare i standardläge eller dedikerat åtkomstläge.
SQL-lager måste vara pro eller serverlösa och måste använda 2025.35 eller senare.

Behörigheter som krävs:

Om du vill skapa en anslutning måste du ha behörigheten CREATE CONNECTION för det metaarkiv som är kopplat till arbetsytan.
CREATE eller MANAGE åtkomst till en Unity Catalog-volym av ansvarig för anslutningen.
Volymåtkomst av användaren som frågar efter anslutningen.
Ytterligare behörigheter anges i varje aktivitetsbaserat avsnitt som följer.

Autentiseringsmetoder

Statiska autentiseringsuppgifter

Autentisering med statiska autentiseringsuppgifter lagrar autentiseringsuppgifter direkt på anslutningen, till exempel ett användarnamn och lösenord, en API-nyckel eller något annat autentiseringsfält som godkänts av JDBC-måldrivrutinen. Autentiseringsuppgifterna skickas till JDBC-drivrutinen as-is när anslutningen används.

OAuth maskin-till-maskin

Important

Den här funktionen finns i Beta. Arbetsyteadministratörer kan styra åtkomsten till den här funktionen från sidan Förhandsversioner . Se Hantera förhandsversioner av Azure Databricks.

OAuth M2M-autentisering (Machine-to-Machine) används när två system eller program kommunicerar utan direkt användarengagemang. Token utfärdas till en registrerad datorklient som använder sina egna autentiseringsuppgifter för att autentisera. Den här autentiseringsmetoden är perfekt för kommunikation från tjänst till tjänst, mikrotjänster och automatiseringsuppgifter där ingen användarkontext behövs.

När JDBC-anslutningen använder OAuth M2M byter Unity Catalog klientautentiseringsuppgifterna vid den konfigurerade tokenslutpunkten och skickar endast den resulterande kortlivade åtkomsttoken till JDBC-drivrutinen med hjälp av drivrutinens tokenparameter.

Steg 1: Skapa en volym och installera JDBC JAR

JDBC-anslutningen läser och installerar JDBC-drivrutins-JAR från en Unity Catalog-volym.

Om du inte har skriv- och läsåtkomst till en befintlig volym skapar du en ny volym:
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
Ladda upp JDBC-drivrutins-JAR:en till volymen.

Bevilja läsåtkomst på volymen till de användare som frågar efter anslutningen:

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

Steg 2: Skapa en JDBC-anslutning

En JDBC-anslutning är ett skyddsbart objekt i Unity Catalog. Den anger JDBC-drivrutinen, URL-sökvägen, autentiseringsuppgifter för åtkomst till ett externt databassystem och tillåtna alternativ som den frågande användaren kan ange. Om du vill skapa en anslutning använder du Catalog Explorer eller CREATE CONNECTION SQL-kommandot i en Azure Databricks-notebook-fil eller Databricks SQL-frågeredigeraren. Se Autentiseringsmetoder för de autentiseringsmetoder som stöds.

Anmärkning

Du kan även använda Databricks REST API eller Databricks CLI för att skapa en anslutning. Se POST /api/2.1/unity-catalog/connections och Unity Catalog-kommandon.

Behörigheter som krävs: Metastore-admin eller användare med CREATE CONNECTION-behörighet.

Observera följande innan du skapar en anslutning:

URL:en och autentiseringsuppgifterna är de enda alternativ som krävs. Bädda inte in autentiseringsuppgifter i URL:en eftersom loggar eller fel kan exponera dem. Använd de dedikerade alternativen för autentiseringsuppgifter för den valda autentiseringsmetoden.
Använd externalOptionsAllowList för att styra vilka Alternativ för Spark-datakälla som användare kan ange vid frågetillfället. Om det inte anges är standardvärdet 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Ange den till en tom sträng för att begränsa användare till endast de alternativ som definierats i anslutningen. Användare kan aldrig ange url eller host.

Katalogutforskaren

På din Azure Databricks-arbetsyta klickar du på Katalog.
Klicka på Anslut och klicka sedan på Anslutningar.
Klicka på Skapa anslutning.
På sidan Anslutningsgrundläggande i Installera anslutningsguiden anger du ett användarvänligt Anslutningsnamn.
Som Anslutningstyp väljer du JDBC.
(Valfritt) Lägg till en kommentar.
Klicka på Nästa.

På sidan Anslutningsinformation anger du följande anslutningsegenskaper:

Property	Description
Url	JDBC-URL:en för databasen i formuläret `jdbc:subprotocol:subname` (till exempel `jdbc:oracle:thin:@<host>:<port>:<SID>`).
Java-beroenden	JDBC-drivrutins-JAR-filer från Unity Catalog-volymer. Klicka på Lägg till JAR-beroende för att lägga till varje JAR (till exempel `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar`).
Lista över tillåtna externa alternativ	Kommaseparerad lista över alternativ för Spark-datakällor som användare kan ange vid frågetillfället. Standardinställningen är `dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions`. Ange ett tomt värde för att begränsa användare till endast de alternativ som definierats för anslutningen.
Ytterligare alternativ	Godtyckliga JDBC-drivrutinsalternativ skickades till drivrutinen som nyckel/värde-par. Använd det här avsnittet om du vill ange databasautentiseringsuppgifter (till exempel nyckel `user` och nyckel `password`) och andra drivrutinsspecifika egenskaper. Växla mellan UI- och JSON-indatalägen efter behov.

Klicka på Skapa anslutning.

OAuth Machine-to-Machine (Beta)

Important

Den här funktionen finns i Beta. Arbetsyteadministratörer kan styra åtkomsten till den här funktionen från sidan Förhandsversioner . Se Hantera förhandsversioner av Azure Databricks.

När förhandsgranskningen jdbc_oauth_m2m_connector är aktiverad på arbetsytan visas fältet Autentiseringstyp på sidan Grundläggande anslutning med alternativ för statisk autentiseringsuppgift och OAuth-dator till dator . Så här skapar du en OAuth M2M JDBC-anslutning:

På sidan Grunderna för anslutning anger du Autentiseringstyp till OAuth-dator till Dator.
Klicka på Nästa.

På sidan Anslutningsinformation anger du följande egenskaper utöver URL ochJava beroenden:

Property	Description
Kund-ID	Det OAuth-klient-ID som utfärdats för programmet.
Klienthemlighet	OAuth-klienthemligheten som utfärdats för programmet.
OAuth-omfång	Omfång för begäran under tokenutbytet. Uttrycks som en blankstegsavgränsad lista över skiftlägeskänsliga strängar.
Tokenslutpunkt	Den OAuth 2.0-tokenslutpunkt som används för att byta ut klientautentiseringsuppgifterna mot en åtkomsttoken. Vanligtvis i formatet `https://authorization-server.com/oauth/token`.
Metod för utbyte av OAuth-autentiseringsuppgifter	Så här skickas klientautentiseringsuppgifterna till tokenslutpunkten: header_and_body – autentiseringsuppgifter skickas i både `Authorization` rubriken och begärandetexten (standard). body_only – endast autentiseringsuppgifter skickas i begärandetexten. header_only – endast autentiseringsuppgifter skickas i `Authorization` rubriken.
JDBC-tokenparameternamn	Egenskapen KEY som krävs av JDBC-måldrivrutinen för att acceptera OAuth-åtkomsttoken. Azure Databricks fyller dynamiskt i parametern VALUE med en genererad giltig OAuth-åtkomsttoken. Typiska KEY:er: `access_token`, `oauthToken`eller `password`. Se JDBC-drivrutinens dokumentation för rätt nyckelnamn för parametern.

Klicka på Skapa anslutning.

SQL

CREATE CONNECTION Använd SQL-kommandot i en notebook-fil eller Databricks SQL-frågeredigeraren.

Statiska autentiseringsuppgifter

Kör följande kommando och justera motsvarande volym, URL, autentiseringsuppgifter och externalOptionsAllowList:

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

Exempel: Oracle JDBC-anslutning

I följande exempel skapas en JDBC-anslutning till en Oracle-databas med hjälp av den tunna Oracle-drivrutinen. Ladda ned Oracle JDBC-drivrutinen JAR (till exempel ojdbc11.jar) från sidan Oracle JDBC-nedladdningar och ladda upp den till en Unity Catalog-volym innan du kör det här kommandot.

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

OAuth-dator till dator

Kör följande kommando och justera motsvarande volym, URL, autentiseringsuppgifter och externalOptionsAllowList:

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

Exempel: PostgreSQL JDBC-anslutning med OAuth M2M

I följande exempel skapas en JDBC-anslutning till en PostgreSQL-databas med OAuth Machine-to-Machine-autentisering. Ladda ned PostgreSQL JDBC-drivrutinen JAR (till exempel postgresql-42.7.3.jar) från sidan PostgreSQL JDBC-nedladdningar och ladda upp den till en Unity Catalog-volym innan du kör det här kommandot. För PostgreSQL-distributioner som har konfigurerats för att acceptera en OAuth-åtkomsttoken i lösenordsfältet anger du jdbc_token_parameter_name till password.

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

Anslutningsägaren eller chefen kan lägga till eventuella extra alternativ som stöds av JDBC-drivrutinen i anslutningen. Av säkerhetsskäl kan alternativ som definierats i anslutningen inte åsidosättas vid frågetillfället.

Steg 3: Bevilja behörigheten `USE`

Bevilja rättigheten för USE-anslutningen till användarna:

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

Information om hur du hanterar befintliga anslutningar finns i Hantera anslutningar för Lakehouse Federation.

Steg 4: Fråga datakällan

Användare med behörigheten USE CONNECTION kan fråga datakällan med hjälp av JDBC-anslutningen via Spark eller SQL API för fjärrfrågor. Användare kan lägga till alternativ för Spark-datakällor som stöds av JDBC-drivrutinen och som anges i externalOptionsAllowList JDBC-anslutningen (till exempel i det här fallet: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Om du vill visa de tillåtna alternativen kör du följande fråga:

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

För att migrera från befintliga API-arbetsbelastningar för Spark-datakälla rekommenderar Databricks att du gör följande:

Ta bort URL:en och autentiseringsuppgifterna från alternativen i Spark Data Source-API:et.
databricks.connection Lägg till i alternativen i Spark Data Source-API:et.
Skapa en JDBC-anslutning med motsvarande URL och autentiseringsuppgifter.
I anslutningen anger du de alternativ som ska vara statiska och som inte ska anges genom att fråga användare.
I anslutningen anger externalOptionsAllowListdu de datakällsalternativ som ska justeras eller ändras av användarna vid frågetillfället i Spark Data Source API-koden (till exempel 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Begränsningar

API för Spark-datakälla

URL och värd kan inte inkluderas i Spark Data Source-API:et.
.option("databricks.connection", "<Connection_name>") måste anges.
Alternativ som definierats i anslutningen kan inte användas i API:et för datakälla i din kod vid frågetillfället.
Endast de alternativ som anges i externalOptionsAllowList kan användas genom att fråga användare.
Minnesgränsen för JDBC-drivrutinen är 400 MiB. Överväg att använda en mindre fetchSize om gränsen har nåtts.

Support

Spark-datakällor stöds inte.
Lakeflow-pipelines stöds inte.
Anslutningsberoende vid skapande: java_dependencies stöder endast volymplatser för JDBC-drivrutins-JAR:er.
Anslutningsberoende vid fråga: Anslutningsanvändaren behöver READ åtkomst till volymen där JDBC-drivrutins-JAR:en finns.
I dedikerat åtkomstläge (tidigare enanvändarläge) måste du vara ägare eller ansvarig för anslutningen för att kunna använda den.
SSL-certifikat stöds inte.
Externa kataloger stöds inte med JDBC-anslutningar.

Authentication

Den här anslutningen stöder statiska autentiseringsuppgifter och OAuth Machine-to-Machine. Den stöder inte autentiseringsuppgifter för Unity Catalog eller autentiseringsuppgifter för tjänsten.

Nätverkande

Måldatabassystemet och Azure Databricks arbetsytan kan inte finnas i samma virtuella nätverk.

Nätverksanslutningar

Nätverksanslutning från beräkningsresursen till måldatabassystemet krävs. Se Nätverksrekommendationer för Lakehouse Federation för allmän nätverksvägledning.

Klassisk beräkning: standardkluster och dedikerade kluster

Azure Databricks virtuella nätverk är konfigurerade för att endast tillåta Spark-kluster. Om du vill ansluta till en annan infrastruktur placerar du måldatabassystemet i ett annat VNet och använder VNet-peering. När VNet-peering har upprättats kontrollerar du anslutningen till connectionTest UDF i klustret eller lagret.

Om dina Azure Databricks arbetsytor och måldatabassystem finns i samma virtuella nätverk rekommenderar Databricks något av följande:

Använd serverlös beräkning.
Konfigurera måldatabasen så att TCP- och UDP-trafik tillåts via portarna 80 och 443 och ange dessa portar i anslutningen.

Serverless

När du använder din JDBC-anslutning på serverlös beräkning kan du konfigurera en brandvägg för serverlös beräkningsåtkomst till måldatabassystemet genom att lägga till utgående IP-adresser i en tillåtna lista. Du kan också konfigurera privat anslutning.

Anslutningstest

Om du vill testa anslutningen mellan Azure Databricks-beräkningen och databassystemet använder du följande UDF:

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

Följande vanliga frågor behandlar beteendet för predicate pushdown för JDBC-anslutningar.

Har JDBC stöd för predicate pushdown?

Yes. Filter skickas som standard ned till fjärrdatabasen för både Spark Data Source API (format('jdbc')) och remote_query SQL-funktionen. Vilka predikat som kan push-överföras beror på JDBC-drivrutinen och dialekten, så kör EXPLAIN på din fråga och inspektera den fysiska planen för att bekräfta vilka filter som skickas till källan. remote_query För SQL-funktionen kan du styra specifika pushdowns (filter, gränser, förskjutningar och aggregeringar) med alternativ som pushdown.filters.enabled; alla är aktiverade som standard.

Predikatnedtryckning är skilt från att göra tabellstatistik tillgänglig för frågeoptimeraren. JDBC- och PySpark-datakällor exponerar inte statistik för frågeoptimeraren för att välja ordning på åtgärder, oavsett om predikat skickas nedåt.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-10

JDBC-anslutning

Fördelar med att använda en JDBC-anslutning

JDBC jämfört med frågefederation

Varför ska du använda JDBC jämfört med PySpark-datakällor?

Så här fungerar det

Innan du börjar

Autentiseringsmetoder

Steg 1: Skapa en volym och installera JDBC JAR

Steg 2: Skapa en JDBC-anslutning

Katalogutforskaren

SQL

Steg 3: Bevilja behörigheten USE

Steg 4: Fråga datakällan

python

SQL

Migration

Begränsningar

API för Spark-datakälla

Support

Authentication

Nätverkande

Nätverksanslutningar

Klassisk beräkning: standardkluster och dedikerade kluster

Serverless

Anslutningstest

FAQ

Har JDBC stöd för predicate pushdown?

Feedback

Ytterligare resurser

Steg 3: Bevilja behörigheten `USE`