JDBC-verbinding

Azure Databricks biedt ondersteuning voor het maken van verbinding met externe databases met behulp van JDBC. U kunt een JDBC Unity Catalog-verbinding gebruiken om een gegevensbron te lezen en schrijven met de Spark-gegevensbron-API of de SQL-API van Azure Databricks Remote Query. De JDBC-verbinding is een beveiligbaar object in Unity Catalog waarmee het JDBC-stuurprogramma, het URL-pad en de referenties voor toegang tot een externe database worden opgegeven. De JDBC-verbinding wordt ondersteund in rekentypen van Unity Catalog, waaronder serverloze, standaardclusters, toegewezen clusters en Databricks SQL.

Voordelen van het gebruik van een JDBC-verbinding

• Lees en schrijf naar gegevensbronnen met behulp van JDBC met de Spark-gegevensbron-API.
• Lees uit gegevensbronnen met JDBC met behulp van de SQL-API voor externe query's.
• Toegang tot de gegevensbron beheerd met behulp van een Unity Catalog-verbinding.
• Maak de verbinding één keer en gebruik deze opnieuw op alle Unity Catalog-rekenprocessen.
• Stabiel voor Spark- en rekenupgrades.
• Verbindingsreferenties zijn verborgen voor de querygebruiker.

JDBC versus query federatie

JDBC is een aanvulling op Query Federation. Databricks raadt aan om queryfederatie om de volgende redenen te kiezen:

• Queryfederatie biedt verfijnd toegangsbeheer en governance op tabelniveau met behulp van een externe catalogus. JDBC Unity Catalog-verbinding biedt alleen beheer op verbindingsniveau.
• Queryfederatie pusht Spark-query's omlaag voor optimale queryprestaties.

Kies er echter voor om een JDBC Unity Catalog-verbinding te gebruiken in de volgende scenario's:

• Uw database wordt niet ondersteund door query-federatie.
• U wilt een specifiek JDBC-stuurprogramma gebruiken.
• U moet schrijven naar de databron met Spark (queryfederatie biedt geen ondersteuning voor schrijfbewerkingen).
• U hebt meer flexibiliteit, prestaties en parallellisatiebeheer nodig via opties voor spark-gegevensbron-API.
• U wilt query's omlaag pushen met de Spark-optie query .

Waarom JDBC versus PySpark-gegevensbronnen gebruiken?

PySpark-gegevensbronnen zijn een alternatief voor de JDBC Spark-gegevensbron.

Een JDBC-verbinding gebruiken:

• Als u de ingebouwde Ondersteuning voor Spark JDBC wilt gebruiken.
• Als u een out-of-the-box JDBC-stuurprogramma wilt gebruiken dat al bestaat.
• Als u Unity Catalog-governance nodig hebt op verbindingsniveau.
• Als u verbinding wilt maken vanaf elk rekentype van Unity Catalog: serverloos, standaard, toegewezen, SQL-API.
• Als u uw verbinding wilt gebruiken met Python-, Scala- en SQL-API's.

Een PySpark-gegevensbron gebruiken:

• Als u de flexibiliteit wilt hebben om uw Spark-gegevensbron of -sink te ontwikkelen en te ontwerpen met behulp van Python.
• Als u het alleen gebruikt in notebooks of PySpark workloads.
• Als u aangepaste partitioneringslogica wilt implementeren.

JDBC- en PySpark-gegevensbronnen bieden geen ondersteuning voor predicaatpushdown. Ze maken ook geen statistieken beschikbaar voor de queryoptimalisatie om de volgorde van bewerkingen te helpen selecteren.

Hoe het werkt

Als u verbinding wilt maken met een gegevensbron met behulp van een JDBC-verbinding, installeert u het JDBC-stuurprogramma op Spark Compute. Met de verbinding kunt u het JDBC-stuurprogramma opgeven en installeren in een geïsoleerde sandbox die toegankelijk is voor Spark-rekenkracht om te zorgen voor Spark-beveiliging en Unity Catalog-governance. Zie Hoe dwingt Databricks gebruikersisolatie af voor meer informatie over sandboxing.

Voordat u begint

Als u een JDBC-verbinding wilt gebruiken met de Spark-gegevensbron-API op serverloze en standaardclusters, moet u eerst voldoen aan de volgende vereisten:

Vereisten voor werkruimte:

• Een Azure Databricks-werkruimte ingeschakeld voor Unity Catalog

Rekenvereisten:

• Netwerkconnectiviteit van uw rekenresource naar het doeldatabasesysteem. Zie Netwerkconnectiviteit.
• Azure Databricks Compute moet serverloos of Databricks Runtime 17.3 LTS of hoger gebruiken in de standaardmodus of toegewezen toegangsmodus.
• SQL-warehouses moeten pro of serverloos zijn en moeten 2025.35 of hoger gebruiken.

Vereiste machtigingen:

• Als u een verbinding wilt maken, moet u beschikken over de CREATE CONNECTION bevoegdheid voor de metastore die is gekoppeld aan de werkruimte.
• CREATE ofwel MANAGE toegang tot een Unity Catalog-volume door degene die de verbinding heeft gemaakt.
• Volumetoegang door de gebruiker die een query op de verbinding uitvoert.
• Aanvullende machtigingen worden gespecificeerd in elke taakgebaseerde sectie die volgt.

Stap 1: Een volume maken en de JDBC JAR installeren

De JDBC-verbinding leest en installeert de JAR van het JDBC-stuurprogramma van een Unity Catalog-volume.

1. Als u geen schrijf- en leestoegang tot een bestaand volume hebt, maakt u een nieuw volume:

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. Upload de JDBC-driver-JAR naar het volume.

3. Leestoegang verlenen aan de gebruikers die een query uitvoeren op de specifieke verbinding:

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

Stap 2: een JDBC-verbinding maken

Een JDBC-verbinding is een beveiligbaar object in Unity Catalog dat het JDBC-stuurprogramma, het URL-pad en de referenties opgeeft voor toegang tot een extern databasesysteem en toegestane opties die door de querygebruiker moeten worden gebruikt. Als u een verbinding wilt maken, gebruikt u Catalog Explorer of de CREATE CONNECTION SQL-opdracht in een Azure Databricks-notebook of de Databricks SQL-queryeditor.

Vereiste machtigingen: Metastore-beheerder of gebruiker met de CREATE CONNECTION bevoegdheid.

Catalogusverkenner

1. Klik in uw Azure Databricks-werkruimte op Catalogus.
2. Klik boven aan het deelvenster Catalogus op het en selecteer Een verbinding maken in het menu.
3. Voer op de pagina Verbindingsbeginselen van de wizard Verbinding instellen een gebruiksvriendelijke verbindingsnaam in.
4. Selecteer een verbindingstype van JDBC.
5. (Optioneel) Voeg een opmerking toe.
6. Klik op Volgende.
7. Voer op de pagina Verificatie de volgende verbindingseigenschappen in:
   • JDBC-URL: de JDBC-verbindings-URL voor uw database (bijvoorbeeld jdbc:oracle:thin:@<host>:<port>:<SID>).
   • Gebruiker: de gebruikersnaam van de database.
   • Wachtwoord: het databasewachtwoord.
   • JDBC-stuurprogrammapad: het volumepad van de Unity-catalogus naar de JAR van het JDBC-stuurprogramma (bijvoorbeeld /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
8. Klik op Verbinding maken.

SQL

Voer de volgende opdracht uit in een notebook of de SQL-queryeditor, waarbij u het volume, de URL, de referenties en externalOptionsAllowList dienovereenkomstig aanpast.

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

Voorbeeld: Oracle JDBC-verbinding

In het volgende voorbeeld wordt een JDBC-verbinding met een Oracle-database gemaakt met behulp van het thin-stuurprogramma van Oracle. Download het ORACLE JDBC-stuurprogramma JAR (bijvoorbeeld ojdbc11.jar) van de downloadpagina van Oracle JDBC en upload het naar een Unity Catalog-volume voordat u deze opdracht uitvoert.

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

De eigenaar of manager van de verbinding kan toevoegen aan de verbinding, eventuele extra opties die worden ondersteund door het JDBC-stuurprogramma.

Om veiligheidsredenen kunnen opties die in de verbinding zijn gedefinieerd, niet worden overschreven tijdens het uitvoeren van query's. Gebruikers kunnen alleen opties voor Spark-gegevensbronnen opgeven die nog niet zijn gedefinieerd in de verbinding.

Hiermee kan de maker van de verbinding aangeven welke Spark-gegevensbronopties gebruikers bij de indiening van een query kunnen opgeven. In dit voorbeeld kunnen gebruikers alleen het volgende gebruiken: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Het externalOptionsAllowList kan een lege tekenreeks zijn om ervoor te zorgen dat alleen de opties die zijn opgegeven in de Unity Catalog-verbinding worden gebruikt. URL en host mogen nooit worden opgegeven door gebruikers.

URL is de enige verplichte optie bij het maken van de verbinding. Als er geen acceptatielijst is opgegeven, wordt er een standaard allowlist gebruikt die het volgende bevat: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'

Databricks raadt aan om de inloggegevens in de verbinding op te geven.

Stap 3: De USE bevoegdheid verlenen

Verleen de USE bevoegdheid op de verbinding aan de gebruikers:

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

Zie Verbindingen beheren voor Lakehouse Federation voor informatie over het beheren van bestaande verbindingen.

Stap 4: Een query uitvoeren op de gegevensbron

Gebruikers met de USE CONNECTION bevoegdheid kunnen gegevensbronnen bevragen met behulp van de JDBC-verbinding via Spark of de SQL API voor externe queries. Gebruikers kunnen spark-gegevensbronopties toevoegen die worden ondersteund door het JDBC-stuurprogramma en die zijn opgegeven in de externalOptionsAllowList JDBC-verbinding (bijvoorbeeld in dit geval: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Voer de volgende query uit om de toegestane opties weer te geven:

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

Databricks raadt het volgende aan om te migreren van bestaande Spark-gegevensbron-API-workloads:

• Verwijder de URL en referenties uit de opties in de Spark-gegevensbron-API.
• Voeg de databricks.connection opties toe in de Spark-gegevensbron-API.
• Maak een JDBC-verbinding met de bijbehorende URL en referenties.
• In de connectie, specificeer de opties die statisch moeten zijn en niet mogen worden opgegeven door gebruikers.
• Geef in de verbinding externalOptionsAllowListde opties voor de gegevensbron op die moeten worden aangepast of gewijzigd door de gebruikers tijdens de query in de API-code van de Spark-gegevensbron (bijvoorbeeld 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Beperkingen

Spark-gegevensbron-API

• URL en host kunnen niet worden opgenomen in de Spark-gegevensbron-API.
• .option("databricks.connection", "<Connection_name>") is vereist.
• Opties die in de verbinding zijn gedefinieerd, kunnen niet worden gebruikt voor de Gegevensbron-API in uw code tijdens de query.
• Alleen de opties die in de externalOptionsAllowList opties zijn opgegeven, kunnen worden gebruikt door gebruikers op te vragen.
• De geheugenlimiet voor het JDBC-stuurprogramma is 400 MiB. Overweeg een kleinere fetchSize limiet te gebruiken als de limiet is bereikt.

Support

• Spark-gegevensbronnen worden niet ondersteund.
• Declaratieve Spark-pijplijnen worden niet ondersteund.
• Verbindingsafhankelijkheid bij het maken: java_dependencies alleen volumelocaties voor JDBC-stuurprogramma-JAR's ondersteunen.
• Afhankelijkheid van verbinding bij query: De verbindingsgebruiker heeft READ toegang nodig tot het volume waar de JDBC-driver JAR zich bevindt.
• In de toegewezen toegangsmodus (voorheen modus voor toegang van één gebruiker) moet u een eigenaar of manager van de verbinding zijn om deze te kunnen gebruiken.
• SSL-certificaten worden niet ondersteund.
• Buitenlandse catalogi worden niet ondersteund met JDBC-verbindingen.

Authenticatie

• Alleen basisverificatie wordt ondersteund (gebruikersnaam en wachtwoord). Er is geen ondersteuning voor Unity Catalog-referenties, OAuth- of servicereferenties.

Networking

• Het doeldatabasesysteem en de Azure Databricks-werkruimte kunnen zich niet in dezelfde VPC bevinden.

Netwerkverbinding

Netwerkconnectiviteit van uw rekenresource naar het doeldatabasesysteem is vereist. Zie De aanbevelingen voor netwerken voor Lakehouse Federation voor algemene netwerkrichtlijnen.

Klassieke berekening: standaard- en toegewezen clusters

VPN's van Azure Databricks zijn zo geconfigureerd dat alleen Spark-clusters zijn toegestaan. Als u verbinding wilt maken met een andere infrastructuur, plaatst u het doeldatabasesysteem in een andere VPC en gebruikt u VPC-peering. Nadat VPC-peering tot stand is gebracht, controleert u uw connectiviteit met de connectionTest UDF op het cluster of warehouse.

Als uw Azure Databricks-werkruimte en doeldatabasesystemen zich in dezelfde VPC bevinden, raadt Databricks een van de volgende opties aan:

• Gebruik serverloze berekeningen.
• Configureer uw doeldatabase om TCP- en UDP-verkeer via poort 80 en 443 toe te staan en geef deze poorten op in de verbinding.

Serverless

Wanneer u uw JDBC-verbinding op serverloze berekeningen gebruikt, configureert u een firewall voor serverloze rekentoegang voor stabiele IP-adressen of configureert u privéconnectiviteit.

Connectiviteitstest

Gebruik de volgende UDF om de connectiviteit tussen azure Databricks compute en uw databasesysteem te testen:

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