Подключение JDBC

Azure Databricks поддерживает подключение к внешним базам данных с помощью JDBC. Вы можете использовать JDBC-подключение к Unity Catalog для чтения и записи данных в источник с помощью API источника данных Spark или SQL API удаленного запроса Azure Databricks. Подключение JDBC — это защищаемый объект в каталоге Unity, указывающий драйвер JDBC, путь URL-адреса и учетные данные для доступа к внешней базе данных. Подключение JDBC поддерживается в типах вычислительных ресурсов каталога Unity, включая бессерверные, стандартные кластеры, выделенные кластеры и Databricks SQL.

Преимущества использования подключения JDBC

• Чтение и запись в источники данных с помощью JDBC с использованием API Spark для работы с источниками данных.
• Чтение из источников данных с использованием JDBC через API удаленного запроса SQL.
• Регламентированный доступ к источнику данных через подключение к каталогу Unity.
• Создайте подключение один раз и повторно используйте его в любом вычислительном ресурсе каталога Unity.
• Стабильность для обновлений Spark и вычислительных процессов.
• Учетные данные подключения скрыты от запрашивающего пользователя.

JDBC и федерация запросов

JDBC дополняет федерацию запросов. Databricks рекомендует выбрать федерацию запросов по следующим причинам:

• Федерация запросов обеспечивает детальное управление доступом и контроль на уровне таблицы с помощью внешнего каталога. Подключение каталога JDBC Unity обеспечивает управление только на уровне подключения.
• Федерация запросов отправляет запросы Spark для оптимальной производительности запросов.

Однако выберите подключение каталога JDBC Unity в следующих сценариях:

• Ваша база данных не поддерживается объединением запросов.
• Вы хотите использовать определенный драйвер JDBC.
• Необходимо записать данные в источник данных с помощью Spark (федерация запросов не поддерживает записи).
• Вам требуется больше гибкости, производительности и параллелизации с помощью параметров API источника данных Spark.
• Вы хотите ускорить выполнение запросов с помощью параметра Spark query.

Зачем использовать источники данных JDBC и PySpark?

Источники данных PySpark являются альтернативой источнику данных JDBC Spark.

Используйте подключение JDBC:

• Если вы хотите использовать встроенную поддержку Spark JDBC.
• Если вы хотите использовать готовый для использования драйвер JDBC, который уже существует.
• Если вам нужна система управления каталогом Unity на уровне подключения.
• Если вы хотите подключиться из любого типа вычислительной среды каталога Unity: бессерверный, стандартный, выделенный, SQL API.
• Если вы хотите использовать подключение с API Python, Scala и SQL.

Используйте источник данных PySpark:

• Если вы хотите иметь гибкость для разработки и проектирования источника данных Spark или сборщика данных с помощью Python.
• Если вы используете его только в среде ноутбуков или в рабочих нагрузках PySpark.
• Если вы хотите реализовать пользовательскую логику секционирования.

Ни JDBC, ни PySpark не поддерживают предикат pushdown. Они также не предоставляют статистику оптимизатору запросов, чтобы помочь выбрать порядок операций.

Принцип работы

Чтобы подключиться к источнику данных с помощью подключения JDBC, установите драйвер JDBC на вычислительные ресурсы Spark. Подключение позволяет указать и установить драйвер JDBC в изолированной песочнице, к которой может получить доступ вычислительная система Spark, чтобы обеспечить безопасность Spark и контроль за каталогом Unity. Для получения дополнительной информации о песочнице см. статью Как Databricks обеспечивает изоляцию пользователей?.

Перед тем как начать

Чтобы использовать подключение JDBC с API источника данных Spark в бессерверных и стандартных кластерах, необходимо сначала выполнить следующие требования:

Требования к рабочей области:

• Рабочая область Azure Databricks, настроенная для использования каталога Unity

Требования к вычислениям:

• Сетевое подключение от вашего вычислительного ресурса к целевой базе данных. См. сведения о подключении к сети.
• Вычисления Azure Databricks должны использовать бессерверный режим или Databricks Runtime 17.3 LTS или выше в стандартном режиме или режиме выделенного доступа.
• Хранилища SQL должны быть профессиональными или бессерверными и должны использовать 2025.35 или более поздней версии.

Необходимые разрешения:

• Чтобы создать подключение, необходимо иметь CREATE CONNECTION права доступа в хранилище метаданных, присоединённом к рабочей области.
• CREATE или MANAGE доступ к каталогу Unity создателем подключения.
• Доступ к тому пользователю, запрашивающим подключение.
• Дополнительные разрешения указываются в каждом следующем разделе, основанном на задачах.

Шаг 1. Создание тома и установка JAR-файла JDBC

Подключение JDBC считывает и устанавливает JAR-файл драйвера JDBC из тома каталога Unity.

1. Если у вас нет доступа на запись и чтение к существующему тому, то создайте новый том:

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. Загрузите JAR-файл драйвера JDBC на том.

3. Предоставьте доступ на чтение тома пользователям, запрашивающим подключение:

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

Шаг 2. Создание подключения JDBC

Подключение JDBC — это защищаемый объект в каталоге Unity, указывающий драйвер JDBC, путь URL-адреса и учетные данные для доступа к внешней системе базы данных, а также разрешенные параметры, которые может использовать пользователь, выполняющий запрос. Чтобы создать подключение, используйте обозреватель каталогов или CREATE CONNECTION команду SQL в записной книжке Azure Databricks или редакторе запросов Databricks SQL.

Необходимые разрешения: администратор хранилища метаданных или пользователь с привилегиями CREATE CONNECTION .

Обозреватель каталогов

1. В рабочей области Azure Databricks щелкните Каталог.
2. В верхней части области каталога щелкните " и выберите "Создать подключение" в меню.
3. На странице Основы подключения мастера Настройка подключения введите удобное для пользователя Имя подключения.
4. Выберите тип подключенияJDBC.
5. (Необязательно) Добавьте комментарий.
6. Нажмите кнопку Далее.
7. На странице проверки подлинности введите следующие свойства подключения:
   • URL-адрес JDBC: URL-адрес подключения JDBC для базы данных (например, jdbc:oracle:thin:@<host>:<port>:<SID>).
   • Пользователь: имя пользователя базы данных.
   • Пароль: пароль базы данных.
   • Путь к драйверу JDBC: путь каталога Unity к JAR-файлу драйвера JDBC (например, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
8. Нажмите Create connection (Создать подключение).

SQL

Выполните следующую команду в записной книжке или редакторе sql-запросов, изменив соответствующий том, URL-адрес, учетные данные и 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>;

Пример: подключение Oracle JDBC

В следующем примере создается подключение JDBC к базе данных Oracle с помощью тонкого драйвера Oracle. Скачайте JAR-файл ДРАЙВЕРА JDBC Oracle (например, ojdbc11.jar) с страницы загрузки Oracle JDBC и отправьте его в том каталога 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'
);

Владелец подключения или менеджер может добавить в подключение любые дополнительные параметры, поддерживаемые драйвером JDBC.

По соображениям безопасности параметры, определенные в соединении, не могут быть переопределены во время запроса. Пользователи могут указывать только параметры источника данных Spark, которые еще не определены в соединении.

Создатель externalOptionsAllowList подключения позволяет указать, какие параметры источника данных Spark могут предоставляться в момент выполнения запроса. В этом примере пользователи могут использовать только следующие возможности. 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions' Это externalOptionsAllowList может быть пустой строкой, чтобы убедиться, что используются только параметры, указанные в подключении к каталогу Unity. URL-адрес и узел никогда не могут быть указаны пользователями.

URL-адрес является единственным обязательным параметром при создании подключения. Если список разрешений не указан, используется список разрешений по умолчанию, содержащий: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'

Databricks рекомендует указать учетные данные в соединении.

Шаг 3. Предоставление привилегий USE

Предоставьте привилегию USE на подключение пользователям:

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

Для получения сведений об управлении существующими подключениями см. статью Управление подключениями для федерации Lakehouse.

Шаг 4. Запрос источника данных

Пользователи с USE CONNECTION привилегией могут запрашивать источник данных с помощью подключения JDBC через Spark или SQL API для удаленных запросов. Пользователи могут добавлять любые параметры источника данных Spark, поддерживаемые драйвером JDBC, и указанные в externalOptionsAllowList подключении JDBC (например, в этом случае: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Чтобы просмотреть разрешенные параметры, выполните следующий запрос:

DESCRIBE CONNECTION <JDBC-connection-name>;

Питон

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

Чтобы выполнить миграцию из существующих рабочих нагрузок API источника данных Spark, Databricks рекомендует выполнить следующие действия:

• Удалите URL-адрес и учетные данные из параметров в API источника данных Spark.
• Добавьте параметры databricks.connection в API источника данных Spark.
• Создайте подключение JDBC с соответствующим URL-адресом и учетными данными.
• В соединении укажите параметры, которые должны быть статическими и не должны быть указаны путем запроса пользователей.
• В соединении externalOptionsAllowListукажите параметры источника данных, которые должны быть скорректированы или изменены пользователями во время запроса в коде API источника данных Spark (например, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Ограничения

API источника данных Spark

• URL-адрес и хост не могут быть добавлены в API источника данных Spark.
• .option("databricks.connection", "<Connection_name>") является обязательным.
• Параметры, определенные в соединении, нельзя использовать в API источника данных в коде во время запроса.
• Запросы пользователей могут использоваться только параметрами, указанными в этом externalOptionsAllowList разделе.
• Ограничение памяти для драйвера JDBC составляет 400 МиБ. Рекомендуется использовать меньший fetchSize размер, если достигнуто ограничение.

Support

• Источники данных Spark не поддерживаются.
• Декларативные конвейеры Spark не поддерживаются.
• Зависимость подключения при создании: java_dependencies поддерживает только расположения томов для JAR-файлов драйвера JDBC.
• Зависимость подключения при запросе: пользователю подключения нужен READ доступ к тому тому, где находится JAR-файл драйвера JDBC.
• В выделенном режиме доступа (ранее однопользовательском режиме доступа) необходимо быть владельцем или руководителем подключения, чтобы использовать его.
• SSL-сертификаты не поддерживаются.
• Внешние каталоги не поддерживаются с подключениями JDBC.

Authentication

• Поддерживается только обычная проверка подлинности (имя пользователя и пароль). Учетные данные каталога Unity, OAuth или сервисные учетные данные не поддерживаются.

Нетворкинг

• Целевая система баз данных и рабочая область Azure Databricks не могут находиться в том же VPC.

Сетевое соединение

Требуется сетевое подключение из вычислительного ресурса к целевой системе базы данных. См. Рекомендации по сетям для Федерации Lakehouse для общих рекомендаций по сети.

Классические вычислительные ресурсы: стандартные и выделенные кластеры

Виртуальные частные сети (VPC) Azure Databricks настроены так, чтобы разрешать доступ только для кластеров Spark. Чтобы подключиться к другой инфраструктуре, поместите целевую систему базы данных в другой VPC и используйте пиринг VPC. После установки пиринга VPC проверьте подключение к connectionTest UDF в кластере или хранилище.

Если рабочая область Azure Databricks и целевые системы баз данных находятся в том же VPC, Databricks рекомендует выполнить одно из следующих действий:

• Использование бессерверных вычислений.
• Настройте целевую базу данных, чтобы разрешить трафик TCP и UDP через порты 80 и 443 и указать эти порты в соединении.

Serverless

При использовании подключения JDBC к бессерверным вычислениям настройте брандмауэр для бессерверного доступа к вычислительным ресурсам для стабильных IP-адресов или настройте частное подключение.

Проверка подключения

Чтобы проверить подключение между вычислительными ресурсами Azure Databricks и системой базы данных, используйте следующую 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>');