Ligação JDBC

O Azure Databricks suporta a ligação a bases de dados externas usando JDBC. Pode usar uma ligação JDBC Unity Catalog para ler e escrever numa fonte de dados com a API Spark Data Source ou Azure Databricks Remote Query SQL API. A ligação JDBC é um objeto seguro no Unity Catalog que especifica o driver JDBC, o caminho URL e as credenciais para aceder a uma base de dados externa. A ligação JDBC é suportada em todos os tipos de computação do Unity Catalog, incluindo serverless, clusters padrão, clusters dedicados e Databricks SQL.

Vantagens de usar uma ligação JDBC

• Leia e escreva em fontes de dados usando JDBC com a API Spark Data Source.
• Leia de fontes de dados com JDBC usando a API SQL de Consulta Remota.
• Regulou o acesso à fonte de dados através de uma ligação ao Unity Catalog.
• Crie a ligação uma vez e reutilize-a em qualquer cálculo do Unity Catalog.
• Estável para Spark e atualizações de computação.
• As credenciais de ligação estão ocultas ao utilizador que faz a consulta.

JDBC versus consulta federada

O JDBC é complementar à federação de consultas. A Databricks recomenda optar pela federação de consultas, pelas seguintes razões:

• A federação de consultas fornece controlos de acesso e governação granulares ao nível da tabela utilizando um catálogo externo. A ligação JDBC Unity Catalog fornece governação apenas ao nível da ligação.
• A federação de consultas descarrega as consultas Spark para otimizar o desempenho das consultas.

No entanto, escolha usar uma ligação JDBC Unity Catalog nos seguintes cenários:

• A sua base de dados não é suportada pela federação de consultas.
• Deves usar um driver JDBC específico.
• Necessitas escrever na fonte de dados utilizando o Spark (a federação de consultas não suporta operações de escrita).
• Precisa de mais flexibilidade, desempenho e controlo de paralelização através das opções da API Spark Data Source.
• Queres enviar as consultas SQL de origem com a opção Spark query .

Porque usar JDBC em vez de fontes de dados PySpark?

As fontes de dados PySpark são uma alternativa à fonte de dados JDBC Spark.

Use uma ligação JDBC:

• Se quiseres usar o suporte JDBC integrado do Spark.
• Se quiseres usar um driver JDBC pré-configurado que já existe.
• Se precisares de governação do Unity Catalog ao nível da ligação.
• Se quiseres ligar-te a partir de qualquer tipo de computação do Unity Catalog: serverless, standard, dedicado, API SQL.
• Se quiseres usar a tua ligação com APIs de Python, Scala e SQL.

Use uma fonte de dados PySpark:

• Se quiser ter flexibilidade para desenvolver e desenhar a sua fonte de dados Spark ou o seu data sink usando Python.
• Se só o utilizares em notebooks ou em tarefas PySpark.
• Se quiseres implementar lógica de particionamento personalizada.

Nem as fontes de dados JDBC nem PySpark expõem estatísticas ao otimizador de consultas para ajudar a selecionar a ordem das operações.

Como funciona

Para se ligar a uma fonte de dados usando uma ligação JDBC, instale o driver JDBC no computador Spark. A ligação permite-lhe especificar e instalar o driver JDBC numa sandbox isolada acessível pelo Spark compute para garantir a segurança do Spark e a governação do Unity Catalog. Para mais informações sobre sandboxing, veja Como é que o Databricks impõe o isolamento do utilizador?.

Requirements

Para usar uma ligação JDBC com a API Spark Data Source em clusters serverless e standard, deve primeiro cumprir os seguintes requisitos:

Requisitos do espaço de trabalho:

• Um espaço de trabalho do Azure Databricks ativado para Unity Catalog

Requisitos de computação:

• Conectividade de rede do seu recurso de computação para o sistema de base de dados alvo. Ver conectividade de rede.
• A computação do Azure Databricks deve usar modo sem servidor, ou Databricks Runtime 17.3 LTS ou superior em modo padrão ou de acesso dedicado.
• Os warehouses SQL devem ser pro ou serverless e devem usar a versão 2025.35 ou superior.

Permissões necessárias:

• Para criar uma ligação, deve ter o privilégio CREATE CONNECTION na metastore associada ao espaço de trabalho.
• CREATE ou MANAGE acesso a um volume do Unity Catalog pelo criador da conexão.
• Acesso a volumes pelo utilizador que consulta a ligação.

Métodos de autenticação

Passo 1: Crie um volume e instale o JDBC JAR

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

1. Se não tiver acesso de escrita e leitura a um volume existente, crie um novo volume:

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. Carrega o JAR do driver JDBC para o volume.

3. Conceder acesso à leitura no volume aos utilizadores que consultarem a ligação:

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

Passo 2: Criar uma ligação JDBC

Uma ligação JDBC é um objeto securável no Unity Catalog. Especifica o driver JDBC, o caminho da URL, credenciais para aceder a um sistema de base de dados externo e opções listadas que o utilizador que consulta pode especificar. Para criar uma ligação, use o Explorador de Catálogos ou o CREATE CONNECTION comando SQL num caderno Azure Databricks ou o editor de consultas SQL do Databricks. Consulte Métodos de autenticação para os métodos de autenticação suportados.

Antes de criar uma ligação, note o seguinte:

• O administrador da metastore ou utilizador que cria a ligação deve ter esse CREATE CONNECTION privilégio.
• O URL e as credenciais são as únicas opções necessárias. Não inclua credenciais no URL, porque os registos ou as mensagens de erro podem expô-las. Utilize as opções de credenciais dedicadas para o método de autenticação escolhido.
• Use externalOptionsAllowList para controlar quais as opções de fonte de dados do Spark que os utilizadores podem especificar no momento da consulta. Se não for especificado, o padrão será 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Defina para uma string vazia para restringir os utilizadores apenas às opções definidas na ligação. Os utilizadores nunca podem especificar url ou host.
• Se a sua base de dados de destino exigir selecionar uma base de dados no momento da consulta (por exemplo, SQL Server, onde a base de dados não está fixada pela URL da ligação), inclua-o databaseexternalOptionsAllowList para que os utilizadores em consulta possam passá-la. database não está na lista de permissões por defeito.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo.

2. Clica Liga, depois clica em Ligações.

3. Clique em Criar conexão.

4. Na página Noções básicas de conexão do assistente Configurar conexão, insira um Nome da conexãoque seja fácil de usar .

5. Para Tipo de Ligação, selecione JDBC.

6. (Opcional) Adicione um comentário.

7. Clique em Next.

8. Na página de detalhes da ligação, introduza as seguintes propriedades da ligação:

   Property	Description
   Url	A URL JDBC para a sua base de dados, no formulário jdbc:subprotocol:subname (por exemplo, jdbc:oracle:thin:@<host>:<port>:<SID>).
   Dependências de Java	Os ficheiros JAR do driver JDBC provenientes de volumes do Unity Catalog. Clique em Adicionar Dependência de JAR para adicionar cada JAR (por exemplo, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
   Lista de permissões para opções externas	Lista separada por vírgulas de opções de fonte de dados Spark que os utilizadores em consulta podem especificar no momento da consulta. O valor padrão é dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. Definido para um valor vazio para restringir os utilizadores apenas às opções definidas na ligação.
   Opções Adicionais	Opções arbitrárias do controlador JDBC passadas ao controlador como pares chave-valor. Use esta secção para definir credenciais de base de dados (por exemplo, chave user e chave password) e quaisquer outras propriedades específicas do driver. Alterne entre modos de entrada UI e JSON conforme necessário.

9. Clique em Criar conexão.

SQL

Usa o CREATE CONNECTION comando SQL num caderno ou no editor de consultas SQL do Databricks.

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

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

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

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

O proprietário ou gestor da ligação pode adicionar à ligação quaisquer opções extra suportadas pelo driver JDBC. Por razões de segurança, as opções definidas na ligação não podem ser anuladas no momento da consulta.

Passo 3: Conceder o USE privilégio

Conceda o USE privilégio sobre a ligação aos utilizadores:

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 o Lakehouse Federation.

Passo 4: Consultar a fonte dos dados

Os utilizadores com esse USE CONNECTION privilégio podem consultar a fonte de dados usando a ligação JDBC através do Spark ou a API SQL de consultas remotas. Os utilizadores podem adicionar quaisquer opções de fonte de dados Spark suportadas pelo driver JDBC e especificadas na externalOptionsAllowList ligação JDBC (por exemplo, neste caso: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Para visualizar as opções permitidas, execute a seguinte consulta:

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

Para bases de dados que exigem selecionar a base de dados alvo no momento da consulta, passe a database opção. O seguinte exemplo do SQL Server também cita os nomes do esquema e das tabelas com parênteses ([...]) para tratar caracteres especiais e palavras reservadas:

SELECT * FROM remote_query(
  '<JDBC-connection-name>',
  database => 'test-db',
  query => 'SELECT TOP 100 * FROM [dbo].[FactFinance]'
);

Migration

Para migrar a partir das cargas de trabalho existentes da API Spark Data Source, o Databricks recomenda fazer o seguinte:

• Remova o URL e as credenciais das opções na API da Spark Data Source.
• Adicione o databricks.connection nas opções da API de Fonte de Dados do Spark.
• Crie uma ligação JDBC com o URL e credenciais correspondentes.
• Na ligação, especifique as opções que devem ser estáticas e que não devem ser especificadas pelos utilizadores em consulta.
• Na ligação externalOptionsAllowList, especifique as opções de fonte de dados que devem ser ajustadas ou modificadas pelos utilizadores no momento da consulta no código da API da Fonte de Dados Spark (por exemplo, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Limitações

API de Fonte de Dados Spark

• O URL e o host não podem ser incluídos na API de Fonte de Dados do Spark.
• .option("databricks.connection", "<Connection_name>") é obrigatório.
• As opções definidas na ligação não podem ser usadas na API Data Source do seu código no momento da consulta.
• Apenas as opções especificadas no externalOptionsAllowList podem ser usadas pelos utilizadores que fazem consultas.
• O limite de memória do driver JDBC é de 400 MiB. Considere usar um menor fetchSize se o limite for atingido.
• A fonte de dados JDBC do Spark não suporta instruções DML arbitrárias, como UPDATE ou DELETE, contra a base de dados externa. Suporta a leitura de dados e acrescentar ou sobrescrever tabelas inteiras, não modificações linha a linha.

Support

• As fontes de dados Spark não são suportadas.
• Os oleodutos de fluxo de lago não são suportados.
• Dependência de ligação na criação: java_dependencies apenas suporta localizações de volumes para JARs de drivers JDBC.
• Dependência da ligação na consulta: O utilizador da ligação precisa READ de acesso ao volume onde está localizado o ficheiro JAR do driver JDBC.
• No modo de acesso dedicado (anteriormente modo de acesso de utilizador único), deve ser proprietário ou gestor da ligação para a utilizar.
• Certificados SSL não são suportados.
• Catálogos estrangeiros não são suportados com conexões JDBC.

Authentication

• Este conector suporta Credencial Estática e OAuth Machine-to-Machine. Não suporta credenciais do Catálogo Unity nem credenciais de serviço.

Rede

• O sistema de base de dados alvo e o espaço de trabalho do Azure Databricks não podem estar no mesmo VNet.

Conectividade de rede

É necessária conectividade de rede do seu recurso de computação para o sistema de base de dados alvo. Consulte as recomendações de networking da Lakehouse Federation para orientações gerais sobre networking.

Computação clássica: clusters padrão e dedicados

Os VNets do Azure Databricks estão configurados para permitir apenas clusters Spark. Para estabelecer ligação a outra infraestrutura, coloque o sistema de base de dados de destino numa VNet diferente e utilize o emparelhamento de VNet. Depois de estabelecer o peering VNet, verifique a sua conectividade com o connectionTest UDF no cluster ou armazém.

Se o seu espaço de trabalho Azure Databricks e os sistemas de base de dados de destino estiverem no mesmo VNet, o Databricks recomenda um dos seguintes:

• Utiliza computação serverless.
• Configure a sua base de dados de destino para permitir tráfego TCP e UDP nas portas 80 e 443, e especifique essas portas na ligação.

Serverless

Ao usar a sua ligação JDBC na computação serverless, pode configurar uma firewall para permitir o acesso da computação serverless ao sistema de base de dados de destino, adicionando endereços IP de saída a uma lista de permissões. Alternativamente, pode configurar a conectividade privada.

Teste de conectividade

Para testar a conectividade entre o cálculo Azure Databricks e o seu sistema de base de dados, utilize o seguinte 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>');

FAQ

As perguntas frequentes seguintes abordam o comportamento do pushdown de predicados para ligações JDBC.

O JDBC suporta o envio de predicados?

Sim. Por defeito, os filtros são enviados para a base de dados remota tanto pela API de origem de dados do Spark (format('jdbc')) como pela função SQL remote_query. Que predicados podem ser transferidos depende do driver JDBC e do dialeto, por isso executa EXPLAIN na tua consulta e inspeciona o plano físico para confirmar que filtros são transferidos para a origem. Na função SQL remote_query, pode controlar operações específicas enviadas para processamento na origem (filtros, limites, offsets e agregações) com opções como pushdown.filters.enabled; todas vêm ativadas por predefinição.

A descida de predicados é distinta de expor estatísticas da tabela ao otimizador de consultas. As fontes de dados JDBC e PySpark não expõem estatísticas ao otimizador de consultas para ajudar a selecionar a ordem das operações, independentemente de os predicados serem pressionados para baixo.