JDBC-anslutning

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.

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 överföra förfrågningar med alternativet Spark 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 stöder predikatnedtryckning. De exponerar inte heller 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.

Steg 1: Skapa en volym och installera JDBC JAR

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

1. 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
   

2. Ladda upp JDBC-drivrutins-JAR:en till volymen.

3. 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 som anger JDBC-drivrutinen, URL-sökvägen och autentiseringsuppgifterna för åtkomst till ett externt databassystem och tillåtna alternativ som ska användas av den frågande användaren. 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.

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

Katalogutforskaren

1. På din Azure Databricks-arbetsyta klickar du på Katalog.
2. Längst upp i fönstret Katalog klickar du på lägg till och väljer Skapa en anslutning på menyn.
3. På sidan Anslutningsgrundläggande i Installera anslutningsguiden anger du ett användarvänligt Anslutningsnamn.
4. Välj en anslutningstyp för JDBC.
5. (Valfritt) Lägg till en kommentar.
6. Klicka på Nästa.
7. På sidan Autentisering anger du följande anslutningsegenskaper:
   • JDBC-URL: JDBC-anslutnings-URL:en för databasen (till exempel jdbc:oracle:thin:@<host>:<port>:<SID>).
   • Användare: Databasens användarnamn.
   • Lösenord: Databaslösenordet.
   • JDBC-drivrutinssökväg: Volymsökvägen för Unity Catalog till JDBC-drivrutinen JAR (till exempel /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
8. Klicka på Skapa anslutning.

SQL

Kör följande kommando i en notebook-fil eller SQL-frågeredigeraren 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'
);

Anslutningsägaren eller chefen kan lägga till ytterligare 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. Användare kan bara ange alternativ för Spark-datakällor som inte redan har definierats i anslutningen.

externalOptionsAllowList Gör det möjligt för anslutningsskapare att ange vilka Alternativ för Spark-datakälla som användare kan ange vid frågetillfället. I det här exemplet kan användarna bara använda: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. externalOptionsAllowList Kan vara en tom sträng för att säkerställa att endast de alternativ som anges i Unity Catalog-anslutningen används. URL och värd får aldrig anges av användare.

URL är det enda obligatoriska alternativet när du skapar anslutningen. Om ingen tillåtlista har angetts används en standardlista som innehåller: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'.

Databricks rekommenderar att du anger autentiseringsuppgifterna i anslutningen.

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 Database native SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in Database native 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.
• Spark deklarativa 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

• Endast grundläggande autentisering stöds (användarnamn och lösenord). Det finns inget stöd för autentiseringsuppgifter för Unity Catalog, OAuth eller autentiseringsuppgifter för tjänsten.

Nätverkande

• Måldatabassystemet och Azure Databricks-arbetsytan kan inte finnas i samma virtuella dator.

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

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

Om din Azure Databricks-arbetsyta och måldatabassystem finns i samma VPC 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 konfigurerar du en brandvägg för serverlös beräkningsåtkomst för stabila IP-adresser eller konfigurerar 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>');