Připojení JDBC

Poznámka:

Tato funkce je ve verzi Public Preview pro Databricks Runtime 18.1 a DBSQL 2025.40 a vyšší. Pro datové sklady SQL se také musíte zaregistrovat do verze Preview funkce Povolení sítě pro izolované úlohy v bezserverových datových skladech SQL.

Azure Databricks podporuje připojení k externím databázím pomocí JDBC. Připojení katalogu Unity JDBC můžete použít ke čtení a zápisu do zdroje dat pomocí rozhraní API zdroje dat Sparku nebo rozhraní SQL API pro vzdálené dotazy Azure Databricks. Připojení JDBC je zabezpečitelný objekt v katalogu Unity, který určuje ovladač JDBC, cestu URL a přihlašovací údaje pro přístup k externí databázi. Připojení JDBC se podporuje napříč výpočetními typy katalogu Unity, včetně bezserverových, standardních clusterů, vyhrazených clusterů a Sql Databricks.

Výhody používání připojení JDBC

Čtení a zápis do zdrojů dat pomocí JDBC s rozhraním API zdroje dat Sparku
Čtení ze zdrojů dat pomocí JDBC pomocí rozhraní SQL API pro vzdálené dotazy
Regulovaný přístup ke zdroji dat pomocí připojení Unity Catalog.
Vytvořte připojení jednou a znovu ho použijte pro všechny výpočetní prostředky katalogu Unity.
Stabilní pro upgrady Sparku a výpočetních prostředků.
Přihlašovací údaje pro připojení jsou skryté uživateli, který provádí dotaz.

JDBC versus federace dotazů

JDBC slouží jako doplněk k federaci dotazů. Databricks doporučuje zvolit federaci dotazů z následujících důvodů:

Federace dotazů poskytuje jemné řízení přístupu a správu řízení na úrovni tabulek s využitím externího katalogu. Připojení JDBC katalogu Unity poskytuje správu pouze na úrovni samotného připojení.
Federování dotazů přeposílá dotazy Sparku pro optimální výkon dotazů.

Poznámka:

Federace dotazů podporuje mnoho oblíbených databází, včetně Oracle, MySQL, PostgreSQL, SQL Serveru a Snowflake. Pokud je vaše databáze podporovaná, databricks doporučuje místo připojení JDBC použít federaci dotazů. Úplný seznam podporovaných databází najdete v tématu Lakehouse Federation .

V následujících scénářích se ale rozhodnete použít připojení katalogu Unity JDBC:

Vaše databáze není podporována federací dotazů.
Chcete použít konkrétní ovladač JDBC.
Ke zdroji dat je potřeba zapisovat pomocí Sparku (federace dotazů nepodporuje zápisy).
Potřebujete větší flexibilitu, výkon a řízení paralelizace prostřednictvím možností rozhraní API zdroje dat Sparku.
Chcete pomocí možnosti Spark query vynutit pushdown zdrojových dotazů SQL.

Proč používat JDBC a zdroje dat PySpark?

Zdroje dat PySpark jsou alternativou ke zdroji dat JDBC Spark.

Použijte připojení JDBC:

Pokud chcete použít integrovanou podporu Sparku JDBC.
Pokud chcete použít připravený ovladač JDBC, který již existuje.
Pokud potřebujete správu katalogu Unity na úrovni připojení.
Pokud se chcete připojit z libovolného typu výpočetního prostředí Katalogu Unity: bezserverového, standardního, vyhrazeného, nebo pomocí rozhraní SQL API.
Pokud chcete použít připojení s rozhraními Python, Scala a SQL API.

Použijte zdroj dat PySpark:

Pokud chcete mít flexibilitu při vývoji a návrhu zdroje dat Sparku nebo jímky dat pomocí Pythonu.
Pokud ho používáte jenom v poznámkových blocích nebo úlohách PySpark.
Pokud chcete implementovat vlastní logiku dělení.

Zdroje dat JDBC ani PySpark nezpřístupňují statistiky optimalizátoru dotazů, aby pomohly vybrat pořadí operací.

Jak to funguje

Pokud se chcete připojit ke zdroji dat pomocí připojení JDBC, nainstalujte ovladač JDBC na výpočetní prostředky Sparku. Připojení umožňuje zadat a nainstalovat ovladač JDBC v izolovaném sandboxu přístupném ze strany výpočetního prostředí Spark, aby se zajistilo zabezpečení Sparku a správa katalogu Unity. Další informace o sandboxu najdete v tématu Jak Databricks vynucuje izolaci uživatelů?.

Než začnete

Pokud chcete použít připojení JDBC s rozhraním API pro zdroj dat Sparku v bezserverových a standardních clusterech, musíte nejprve splnit následující požadavky:

Požadavky na pracovní prostor:

Pracovní prostor Azure Databricks povolený pro Katalog Unity

Požadavky na výpočetní prostředky:

Síťové připojení z vašeho výpočetního prostředku k cílovému databázovému systému. Viz Připojení k síti.
Výpočetní prostředky Azure Databricks musí používat bezserverové prostředí nebo Databricks Runtime 17.3 LTS nebo vyšší ve standardním nebo vyhrazeném režimu přístupu.
Sql Warehouse musí být pro nebo bezserverové a musí používat verzi 2025.35 nebo vyšší.

Požadovaná oprávnění:

Pokud chcete vytvořit připojení, musíte mít CREATE CONNECTION oprávnění k metastoru připojenému k pracovnímu prostoru.
CREATE nebo MANAGE přístup ke svazku katalogu Unity ze strany tvůrce připojení.
Přístup uživatele ke svazku při dotazování připojení.
Další oprávnění jsou zadána v každé následující části založené na úlohách.

Metody ověřování

Statické přihlašovací údaje

Statické ověřování přihlašovacích údajů ukládá přihlašovací údaje přímo do připojení – například uživatelské jméno a heslo, klíč rozhraní API nebo jakékoli jiné pole přihlašovacích údajů přijaté cílovým ovladačem JDBC. Přihlašovací údaje se předávají ovladači JDBC as-is při použití připojení.

OAuth Machine-to-Machine

Important

Tato funkce je v beta verzi. Správci pracovního prostoru můžou řídit přístup k této funkci ze stránky Previews . Viz Manage Azure Databricks preview.

Ověřování OAuth Machine-to-Machine (M2M) se používá, když dva systémy nebo aplikace komunikují bez přímého zásahu uživatele. Tokeny se vydávají pro registrovaného klienta počítače, který k ověření používá vlastní přihlašovací údaje. Tato metoda ověřování je ideální pro komunikaci mezi službami, mikroslužby a úlohy automatizace, ve kterých není potřeba žádný kontext uživatele.

Když připojení JDBC používá OAuth M2M, Unity Catalog vyměňuje přihlašovací údaje klienta v nakonfigurovaném koncovém bodu tokenu a předává pouze výsledný krátkodobý přístupový token ovladači JDBC pomocí parametru tokenu ovladače.

Krok 1: Vytvoření svazku a instalace JDBC JAR

Připojení JDBC přečte a nainstaluje soubor JAR ovladače JDBC ze svazku úložiště katalogu Unity.

Pokud nemáte přístup pro zápis a čtení k existujícímu svazku, vytvořte nový svazek:
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
Nahrajte soubor JAR ovladače JDBC na svazek.
Udělte na svazku přístup pro čtení uživatelům, kteří se dotazují na připojení:
```
GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
```

Krok 2: Vytvoření připojení JDBC

Připojení JDBC je zabezpečitelný objekt v katalogu Unity. Určuje ovladač JDBC, cestu URL, přihlašovací údaje pro přístup k externímu databázovému systému a možnosti seznamu povolených, které může zadat uživatel dotazu. Pokud chcete vytvořit připojení, použijte Průzkumníka katalogu nebo CREATE CONNECTION příkaz SQL v poznámkovém bloku Azure Databricks nebo editoru dotazů SQL Databricks. Podporované metody ověřování najdete v tématu Metody ověřování .

Poznámka:

K vytvoření připojení můžete použít také rozhraní REST API Databricks nebo rozhraní příkazového řádku Databricks. Viz POST /api/2.1/unity-catalog/connections a příkazy Unity Catalog .

Požadovaná oprávnění : správce metastoru nebo uživatel s oprávněním CREATE CONNECTION.

Než vytvoříte připojení, mějte na paměti následující:

Jedinou požadovanou možností jsou adresy URL a přihlašovací údaje. Nevkládejte přihlašovací údaje do adresy URL, protože protokoly nebo chyby je můžou vystavit. Pro zvolenou metodu ověřování použijte vyhrazené možnosti přihlašovacích údajů.
Slouží externalOptionsAllowList k řízení možností zdroje dat Sparku, které můžou uživatelé zadat v době dotazu. Pokud není zadáno, výchozí hodnota je 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Nastavte ho na prázdný řetězec, aby byli uživatelé omezeni pouze na možnosti definované v připojení. Uživatelé nemohou nikdy zadat url nebo host.

Průzkumník katalogu

V pracovním prostoru Azure Databricks klikněte na Katalog.
Klikněte na Připojte se a potom klikněte na připojení.
Klikněte na Vytvořit připojení.
Na stránce základy připojení průvodce Nastavení připojení zadejte uživatelsky přívětivý název připojení.
Jako typ připojení vyberte JDBC.
(Volitelné) Přidejte komentář.
Klikněte na tlačítko Další.

Na stránce Podrobnosti připojení zadejte následující vlastnosti připojení:

Vlastnictví	Description
Adresa URL	Adresa URL JDBC pro vaši databázi ve formuláři `jdbc:subprotocol:subname` (například `jdbc:oracle:thin:@<host>:<port>:<SID>`).
Závislosti Java	Soubory JAR ovladače JDBC ze svazků katalogu Unity. Kliknutím na Přidat závislost JAR přidejte jednotlivé soubory JAR (například `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar`).
Seznam povolených externích možností	Seznam oddělený čárkami možností zdroje dat Spark, které mohou uživatelé zadat při spuštění dotazu. Výchozí hodnota je `dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions`. Nastavte na prázdnou hodnotu, která omezí uživatele jenom na možnosti definované v připojení.
Další možnosti	Libovolné možnosti ovladače JDBC předávané do ovladače ve formě dvojic klíč–hodnota. V této části můžete nastavit přihlašovací údaje databáze (například klíč `user` a klíč `password`) a všechny další vlastnosti specifické pro ovladač. Podle potřeby můžete přepínat mezi režimy uživatelského rozhraní a vstupu JSON .

Klikněte na Vytvořit připojení.

OAuth komunikace mezi počítači (beta)

Important

Tato funkce je v beta verzi. Správci pracovního prostoru můžou řídit přístup k této funkci ze stránky Previews . Viz Manage Azure Databricks preview.

Když je ve vašem pracovním prostoru povolený jdbc_oauth_m2m_connector náhled, na stránce Základy připojení se zobrazí pole Typ autentizace s možnostmi Statické přihlašovací údaje a OAuth Machine to Machine. Postup vytvoření připojení OAuth M2M JDBC:

Na stránce Základy připojení nastavte Typ ověřování na OAuth Machine to Machine.
Klikněte na tlačítko Další.

Na stránce Podrobnosti připojení zadejte kromě adresy URL a Java závislostí následující vlastnosti:

Vlastnictví	Description
ID klienta	ID klienta OAuth vydané pro aplikaci.
Tajný klíč klienta	Tajný klíč klienta OAuth vydaný pro aplikaci.
Rozsah OAuth	Rozsah oprávnění, který se má vyžádat při výměně tokenů. Vyjádřeno jako seznam řetězců oddělených mezerou, u nichž se rozlišují velká a malá písmena.
Koncový bod tokenu	Koncový bod tokenu OAuth 2.0 sloužící k výměně přihlašovacích údajů klienta pro přístupový token. Obvykle ve formátu `https://authorization-server.com/oauth/token`.
Metoda výměny přihlašovacích údajů OAuth	Jak se přihlašovací údaje klienta předávají koncovému bodu tokenu: header_and_body – přihlašovací údaje se posílají v hlavičce i textu `Authorization` požadavku (výchozí). body_only – přihlašovací údaje se odesílají pouze v textu požadavku. header_only – přihlašovací údaje se odesílají jenom v `Authorization` hlavičce.
Název parametru tokenu JDBC	Vlastnost KEY vyžadovaná cílovým ovladačem JDBC pro přijetí přístupového tokenu OAuth. Azure Databricks dynamicky naplní hodnotu tohoto parametru vygenerovaným platným přístupovým tokenem OAuth. Typické KEY: `access_token`, `oauthToken`nebo `password`. Správný název klíče parametru najdete v dokumentaci ovladače JDBC.

Klikněte na Vytvořit připojení.

SQL

CREATE CONNECTION Použijte příkaz SQL v poznámkovém bloku nebo editoru dotazů SQL Databricks.

Statické přihlašovací údaje

Spusťte následující příkaz a upravte odpovídající svazek, adresu URL, přihlašovací údaje a 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>;

Příklad: Připojení Oracle JDBC

Následující příklad vytvoří připojení JDBC k databázi Oracle pomocí tenkého ovladače Oracle. Stáhněte soubor JAR ovladače Oracle JDBC (například ojdbc11.jar) ze stránky pro stahování Oracle JDBC a před spuštěním tohoto příkazu ho nahrajte do svazku katalogu Unity.

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 Machine-to-Machine

Spusťte následující příkaz a upravte odpovídající svazek, adresu URL, přihlašovací údaje a 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'
);

Příklad: Připojení PostgreSQL JDBC s OAuth M2M

Následující příklad vytvoří připojení JDBC k databázi PostgreSQL pomocí ověřování OAuth Machine-to-Machine. Stáhněte soubor JAR ovladače PostgreSQL JDBC (například postgresql-42.7.3.jar) ze stránky pro stažení PostgreSQL JDBC a před spuštěním tohoto příkazu ho nahrajte do svazku katalogu Unity. Pro nasazení PostgreSQL nakonfigurovaná tak, aby přijímala přístupový token OAuth v poli pro heslo, nastavte jdbc_token_parameter_name na 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'
);

Vlastník nebo správce připojení může do připojení přidat všechny další možnosti podporované ovladačem JDBC. Z bezpečnostních důvodů není možné v době dotazu přepsat možnosti definované v připojení.

Krok 3: Udělení `USE` oprávnění

USE Udělte oprávnění pro připojení uživatelům:

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

Informace o správě existujících připojení naleznete v tématu Správa připojení proLakehouse Federation .

Krok 4: Dotazování zdroje dat

Uživatelé s USE CONNECTION oprávněním mohou provádět dotazy na zdroj dat pomocí připojení JDBC prostřednictvím Sparku nebo pomocí rozhraní SQL API pro vzdálené dotazy. Uživatelé mohou přidat jakékoli možnosti zdroje dat Sparku podporované ovladačem JDBC a zadané v externalOptionsAllowList připojení JDBC (například v tomto případě: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Pokud chcete zobrazit povolené možnosti, spusťte následující dotaz:

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

Pokud chcete migrovat ze stávajících úloh rozhraní API zdroje dat Sparku, doporučuje Databricks provést následující kroky:

Odeberte adresu URL a přihlašovací údaje z možností v rozhraní API zdroje dat Sparku.
Přidejte možnost databricks.connection do rozhraní API zdroje dat Sparku.
Vytvořte připojení JDBC s odpovídající adresou URL a přihlašovacími údaji.
V připojení zadejte možnosti, které by měly být statické a neměly by být určeny dotazováním uživatelů.
V připojení externalOptionsAllowList zadejte možnosti zdroje dat, které by uživatelé měli upravit v době dotazu v kódu Spark Data Source API (například 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Omezení

Rozhraní API zdroje dat Sparku

Adresu URL a hostitele nelze zahrnout do rozhraní API zdroje dat Sparku.
.option("databricks.connection", "<Connection_name>") je povinné.
Možnosti definované v připojení nelze použít v rozhraní API zdroje dat v kódu v době dotazu.
Uživatelé, kteří se dotazují, mohou používat pouze možnosti specifikované v externalOptionsAllowList.
Limit paměti pro ovladač JDBC je 400 MiB. Pokud dosáhnete limitu, zvažte použití menší fetchSize hodnoty.

Support

Zdroje dat Sparku se nepodporují.
Lakeflow pipelines nejsou podporovány.
Závislost připojení při vytváření: java_dependencies Podporují pouze umístění svazků pro JAR ovladače JDBC.
Závislost připojení v dotazu: Uživatel připojení potřebuje READ přístup ke svazku, na kterém se nachází soubor JAR ovladače JDBC.
V režimu vyhrazeného přístupu (dříve režimu přístupu s jedním uživatelem) musíte být vlastníkem nebo správcem připojení, aby ho mohli používat.
Certifikáty SSL nejsou podporovány.
Zahraniční katalogy nejsou podporovány u připojení JDBC.

Autentizace

Tento konektor podporuje statické přihlašovací údaje a OAuth Machine-to-Machine. Nepodporuje přihlašovací údaje katalogu Unity ani přihlašovací údaje služby.

Sítě

Cílový databázový systém a pracovní prostor Azure Databricks nemůže být ve stejné virtuální síti.

Síťové připojení

Vyžaduje se síťové připojení z vašeho výpočetního prostředku k cílovému databázovému systému. Obecné doprovodné materiály k sítím najdete v doporučeních k sítím pro Lakehouse Federation .

Klasické výpočetní prostředky: standardní a vyhrazené clustery

Azure Databricks virtuální sítě jsou nakonfigurované tak, aby povolovaly pouze clustery Spark. Pokud se chcete připojit k jiné infrastruktuře, umístěte cílový databázový systém do jiné virtuální sítě a použijte partnerský vztah virtuálních sítí. Po navázání partnerského propojení virtuálních sítí ověřte připojení pomocí funkce connectionTest UDF v clusteru nebo datovém skladu.

Pokud jsou vaše Azure Databricks pracovní prostor a cílové databázové systémy ve stejné virtuální síti, doporučuje Databricks jednu z následujících možností:

Používejte bezserverové výpočetní prostředky.
Nakonfigurujte cílovou databázi tak, aby umožňovala přenosy TCP a UDP přes porty 80 a 443, a zadejte tyto porty v připojení.

Serverless

Při použití připojení JDBC na bezserverové výpočetní prostředky můžete nakonfigurovat bránu firewall pro bezserverový výpočetní přístup k cílovému databázovému systému přidáním odchozích IP adres do seznamu povolených. Případně můžete nakonfigurovat privátní připojení.

Test připojení

Pokud chcete otestovat připojení mezi výpočetním prostředím Azure Databricks a vaším databázovým systémem, použijte následující 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>');

časté otázky

Následující často kladené otázky se týkají chování při vynucení predikátů pro připojení JDBC.

Podporuje JDBC přenos predikátů?

Yes. Filtry se ve výchozím nastavení přenášejí do vzdálené databáze jak u rozhraní Spark Data Source API (format('jdbc')), tak u funkce remote_query SQL. To, které predikáty lze předat do zdroje, závisí na ovladači JDBC a dialektu, takže spusťte EXPLAIN nad svým dotazem a zkontrolujte fyzický plán, abyste ověřili, které filtry jsou předány do zdroje. U funkce remote_query SQL můžete řídit konkrétní operace pushdown (filtry, limity, offsety a agregace) pomocí možností, jako je pushdown.filters.enabled; všechny jsou ve výchozím nastavení povoleny.

Zatlačování predikátů se liší od zpřístupnění statistik tabulky optimalizátoru dotazů. Zdroje dat JDBC a PySpark neposkytují optimalizátoru dotazů statistiky, které by mu pomohly určit pořadí operací, bez ohledu na to, zda jsou predikáty předávány níže.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-10

Připojení JDBC

Výhody používání připojení JDBC

JDBC versus federace dotazů

Proč používat JDBC a zdroje dat PySpark?

Jak to funguje

Než začnete

Metody ověřování

Krok 1: Vytvoření svazku a instalace JDBC JAR

Krok 2: Vytvoření připojení JDBC

Průzkumník katalogu

SQL

Krok 3: Udělení USE oprávnění

Krok 4: Dotazování zdroje dat

Python

SQL

Migration

Omezení

Rozhraní API zdroje dat Sparku

Support

Autentizace

Sítě

Síťové připojení

Klasické výpočetní prostředky: standardní a vyhrazené clustery

Serverless

Test připojení

časté otázky

Podporuje JDBC přenos predikátů?

Váš názor

Další materiály

Krok 3: Udělení `USE` oprávnění