Pular para o conteúdo principal
Última atualização em

ConexãoJDBC Unity Catalog

nota

Este recurso está em versão Beta no Databricks Runtime 17.3 e superior.

O Databricks oferece suporte à conexão com bancos de dados externos usando JDBC. Você pode usar uma conexão JDBC Unity Catalog para ler e gravar em uma fonte de dados com a APISpark Fonte de Dados ou a API Databricks APIQuery SQL. A conexão JDBC é um objeto protegível no Unity Catalog que especifica o driver JDBC, o caminho da URL e as credenciais para acessar um banco de dados externo. A conexão JDBC é compatível com todos os tipos compute Unity Catalog , incluindo computação serverless, clusters padrão, clusters dedicados e Databricks SQL.

Benefícios de usar uma conexão JDBC​

  • Leia e grave na fonte de dados usando JDBC com a API Spark fonte de dados.
  • Leia dados da fonte de dados com JDBC usando a API SQL de consulta remota.
  • Controle de acesso à fonte de dados usando uma conexão com o Unity Catalog.
  • Crie a conexão uma única vez e reutilize-a em qualquer compute Unity Catalog .
  • Estável para atualizações Spark e compute .
  • As credenciais de conexão ficam ocultas para o usuário que está fazendo a consulta.

JDBC versus federação de consultas​

O JDBC é complementar à federação de consultas. A Databricks recomenda a escolha da federação de consultas pelos seguintes motivos:

  • A federação de consultas oferece controles de acesso refinados e governança em nível de tabela usando um catálogo externo. A conexão JDBC Unity Catalog fornece governança apenas no nível da conexão.
  • A federação de consultas prioriza as consultas Spark para otimizar o desempenho das consultas.

No entanto, opte por usar uma conexão JDBC Unity Catalog nos seguintes cenários:

  • Seu banco de dados não é compatível com federação de consultas.
  • Você deseja usar um driver JDBC específico.
  • Você precisa escrever na fonte de dados usando Spark (a federação de consultas não suporta gravações).
  • Você precisa de mais flexibilidade, desempenho e controle de paralelização por meio das opções da API Spark .
  • Você deseja executar consultas com a opção Spark query .

Por que usar fonte de dados JDBC vs. PySpark ?​

PySpark fonte de dados é uma alternativa à fonte de dados JDBC Spark .

Utilize uma conexão JDBC:

  • Se você deseja usar o suporte JDBC integrado Spark .
  • Se você quiser usar um driver JDBC pronto para uso que já exista.
  • Se você precisar de governança Unity Catalog no nível da conexão.
  • Se você deseja se conectar a partir de qualquer tipo compute Unity Catalog : serverless, standard, dedicated, SQL API.
  • Se você deseja usar sua conexão com APIs Python, Scala e SQL.

Utilize uma fonte de dados PySpark :

  • Se você deseja ter a flexibilidade de desenvolver e projetar sua fonte de dados Spark ou coletor de dados usando Python.
  • Se você for usá-lo apenas em notebooks ou cargas de trabalho PySpark .
  • Se você deseja implementar uma lógica de particionamento personalizada.

Nem JDBC nem PySpark fonte de dados suportam pushdown de predicado. Eles também não expõem estatísticas ao otimizador de consultas para ajudar a selecionar a ordem das operações.

Como funciona​

Para conectar-se a uma fonte de dados usando uma conexão JDBC , instale o driver JDBC no Spark compute. Essa conexão permite especificar e instalar o driver JDBC em um sandbox isolado acessível pelo Spark compute , garantindo a segurança Spark e a governança Unity Catalog . Para obter mais informações sobre o sandbox, consulte Como Databricks impõe o isolamento do usuário?

Antes de começar​

Para usar uma conexão JDBC com a API Spark fonte de dados em clusters serverless e padrão, você deve primeiro atender aos seguintes requisitos:

Requisitos do workspace:

  • Um workspace Databricks habilitado para Unity Catalog

Requisitos de computação:

  • Conectividade de rede entre seu recurso compute e o sistema de banco de dados de destino. Consulte Conectividade de rede.
  • Databricks compute deve usar o serverless ou Databricks Runtime 17.3 LTS ou superior, no modo padrão ou no modo de acesso dedicado.
  • SQL Warehouse deve ser Pro ou serverless e deve usar a versão 2025.35 ou superior.

Permissões necessárias:

  • Para criar uma conexão, você deve ser um administrador do metastore ou um usuário com o privilégio CREATE CONNECTION no metastore anexado ao workspace.
  • CREATE ou MANAGE acesso a um volume Unity Catalog por meio do criador de conexão
  • Acesso ao volume pelo usuário que consulta a conexão.
  • Outros requisitos de permissão são definidos em cada seção baseada em tarefa a seguir.

Passo 1: Crie um volume e instale o JAR JDBC​

A conexão JDBC lê e instala o JAR do driver JDBC a partir de um volume Unity Catalog .

  1. Se você não tiver permissão de leitura e gravação em um volume existente, crie um novo volume:

    SQL
    CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs

  2. Faça o upload do arquivo JAR do driver JDBC para o volume.

  3. Conceda acesso de leitura ao volume aos usuários que consultarão a conexão:

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

o passo 2: Criar uma conexão JDBC​

Um objeto protegível no Unity Catalog que especifica o driver JDBC, o caminho da URL e as credenciais para acessar um sistema de banco de dados externo, além de opções permitidas para o usuário que realiza a consulta. Para criar uma conexão, você pode usar o Catalog Explorer ou o comando SQL CREATE CONNECTION em um Notebook Databricks ou no editor de consultas Databricks SQL .

nota

Você também pode usar a API REST do Databricks ou a CLI do Databricks para criar uma conexão. Consulte POST /api/2.1/unity-catalog/connections e comandoUnity Catalog.

Permissões necessárias: Administrador do Metastore ou usuário com o privilégio CREATE CONNECTION.

Execute o seguinte comando em um Notebook ou no editor de consultas SQL , ajustando o volume, URL, credenciais e externalOptionsAllowList correspondentes:

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

O proprietário ou administrador da conexão pode adicionar à conexão quaisquer opções extras que sejam suportadas pelo driver JDBC.

Por motivos de segurança, as opções definidas na conexão não podem ser alteradas no momento da consulta. Os usuários só podem especificar opções do Spark que ainda não estejam definidas na conexão.

O externalOptionsAllowList permite que o criador da conexão especifique quais opções do Spark podem ser fornecidas pelos usuários no momento da consulta. Neste exemplo, os usuários só podem usar: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. O externalOptionsAllowList pode ser uma string vazia para garantir que apenas as opções especificadas na Conexão UC sejam usadas. Os usuários nunca podem especificar URL e host.

O URL é a única opção obrigatória ao criar a conexão. Se nenhuma lista de permissões for especificada, será usada uma lista de permissões default que contém: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'.

A Databricks recomenda especificar as credenciais na conexão.

o passo 3: Conceda o privilégio USE​

Conceda o privilégio USE na conexão aos usuários:

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

Para obter informações sobre como gerenciar conexões existentes, consulte Gerenciar conexões para a Federação Lakehouse.

o passo 4: Consultar a fonte de dados​

Usuários com privilégio USE CONNECTION podem consultar a fonte de dados usando a conexão JDBC via Spark ou a API SQL de consultas remotas. Os usuários podem adicionar quaisquer opções de fonte de dados Spark que sejam suportadas pelo driver JDBC e especificadas no externalOptionsAllowList na conexão JDBC (por exemplo, neste caso: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Para view as opções permitidas, execute a seguinte consulta:

SQL
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()

Migração​

Para migrar de cargas de trabalho existentes API Spark fonte de dados, Databricks recomenda fazer o seguinte:

  • Remova a URL e as credenciais das opções na API Spark fonte de dados.
  • Adicione o databricks.connection nas opções da API Spark fonte de dados.
  • Crie uma conexão JDBC com a URL e as credenciais correspondentes.
  • Na conexão. Especifique as opções que devem ser estáticas e não devem ser definidas pelos usuários que fizerem a consulta.
  • Na conexão externalOptionsAllowList, especifique as opções de fonte de dados que devem ser ajustadas ou modificadas pelos usuários no momento da consulta no código API de fonte de dados Spark (por exemplo, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Limitações​

APISpark fonte de dados​

  • URL e host não podem ser incluídos na API Spark fonte de dados.
  • .option("databricks.connection", "<Connection_name>") é obrigatório.
  • As opções definidas na conexão não podem ser usadas na API fonte de dados em seu código no momento da consulta.
  • Somente as opções especificadas em externalOptionsAllowList podem ser usadas pelos usuários que fazem consultas.

Apoiar​

  • Fontes de dados Spark não são suportadas.
  • O pipeline declarativo Spark não é suportado.
  • Dependência de conexão na criação: java_dependencies suporta apenas locais de volume para JARs de driver JDBC.
  • Dependência de conexão na consulta: O usuário da conexão precisa de acesso READ ao volume onde o JAR do driver JDBC está localizado.

Autenticação​

  • Apenas a autenticação básica é suportada (nome de usuário e senha). Não há suporte para credenciais do Unity Catalog, OAuth ou credenciais de serviço.

Redes de contatos​

  • O sistema de banco de dados de destino e o workspace Databricks não podem estar na mesma VPC.

Conectividade de rede​

É necessária conectividade de rede entre o seu recurso compute e o sistema de banco de dados de destino. Consulte as recomendações de rede da Lakehouse Federation para obter orientações gerais sobre redes.

compute clássica: clusterspadrão e dedicados​

As VPCs do Databricks estão configuradas para permitir apenas clusters Spark. Para conectar-se a outra infraestrutura, coloque o sistema de banco de dados de destino em uma VPC diferente e use o peering de VPC. Após o estabelecimento do peering VPC, verifique sua conectividade com o UDF connectionTest no cluster ou warehouse.

Se o seu workspace Databricks e os sistemas de banco de dados de destino estiverem na mesma VPC, Databricks recomenda uma das seguintes opções:

  • Utilize compute serverless
  • Configure seu banco de dados de destino para permitir tráfego TCP e UDP nas portas 80 e 443 e especifique essas portas na conexão.

Teste de conectividade​

Para testar a conectividade entre o Databricks compute e seu sistema de banco de dados, use a seguinte UDF:

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