Conexão JDBC

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

Benefícios de usar uma conexão JDBC

• Ler e gravar em fontes de dados usando JDBC com a API de Fonte de Dados do Spark.
• Ler a partir de fontes de dados com JDBC usando a API SQL de Consulta Remota.
• Acesso governado à fonte de dados usando uma conexão do Unity Catalog.
• Crie a conexão uma vez e reutilize-a em qualquer recurso computacional do Unity Catalog.
• Estável para atualizações de Spark e de capacidade computacional.
• As credenciais de conexão estão ocultas do usuário que está consultando.

JDBC versus federação de consulta

O JDBC é complementar à federação de consulta. O Databricks recomenda escolher a federação de consulta pelos seguintes motivos:

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

No entanto, escolha usar uma conexão com o Catálogo Unity JDBC nos seguintes cenários:

• O seu banco de dados não é compatível com a federação de consultas.
• Você deseja usar um driver JDBC específico.
• Você precisa gravar na fonte de dados usando o 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 de API da Fonte de Dados do Spark.
• Você deseja aplicar pushdown às consultas SQL de origem com a opção Spark query.

Por que usar fontes de dados JDBC versus PySpark?

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

Use uma conexão JDBC:

• Se você quiser usar o suporte interno do Spark JDBC.
• Se você quiser usar um driver JDBC pronto para uso que já existe.
• Se você precisar de governança do Unity Catalog no nível da conexão.
• Se você quiser se conectar de qualquer tipo de computação do Unity Catalog: sem servidor, padrão, dedicada, API SQL.
• Se você quiser usar sua conexão com as APIs Python, Scala e SQL.

Use uma fonte de dados do PySpark:

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

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

Como funciona

Para se conectar a uma fonte de dados usando uma conexão JDBC, instale o driver JDBC na computação do Spark. A conexão permite especificar e instalar o driver JDBC em uma sandbox isolada acessível pela computação Spark para garantir a segurança do Spark e a governança do Unity Catalog. Para mais informações sobre sandboxing, consulte Como o Databricks impõe o isolamento do usuário?.

Antes de começar

Para usar uma conexão JDBC com a API de Fonte de Dados do Spark em clusters padrão e sem servidor, primeiro você deve atender aos seguintes requisitos:

Requisitos de workspace:

• Um workspace do Azure Databricks habilitado para o Catálogo do Unity

Requisitos de computação:

• Conectividade de rede do recurso de computação para o sistema de banco de dados de destino. Consulte conectividade de rede.
• A computação do Azure Databricks deve usar sem servidor ou Databricks Runtime 17.3 LTS ou superior no modo padrão ou no modo de acesso dedicado.
• Os sql warehouses devem ser profissionais ou sem servidor e devem usar 2025.35 ou superior.

Permissões necessárias:

• Para criar uma conexão, você deve ter o privilégio CREATE CONNECTION no metastore associado ao workspace.
• CREATE ou MANAGE acesso a um volume do Unity Catalog pelo criador da conexão.
• Acesso ao volume pelo usuário que está consultando a conexão.
• Permissões adicionais são especificadas em cada seção baseada em tarefa a seguir.

Métodos de autenticação

Etapa 1: Criar um volume e instalar o JAR JDBC

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

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

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. Carregue o JAR do driver JDBC no volume.

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

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

Etapa 2: Criar uma conexão JDBC

Uma conexão JDBC é um objeto protegível no Catálogo do Unity. Ele especifica o driver JDBC, o caminho da URL, as credenciais para acessar um sistema de banco de dados externo e as opções de lista de permissões que o usuário de consulta pode especificar. Para criar uma conexão, use o Gerenciador de Catálogos ou o CREATE CONNECTION comando SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks. Consulte os métodos de autenticação para os métodos de autenticação com suporte.

Permissões necessárias: administrador do metastore ou usuário que possua o privilégio CREATE CONNECTION.

Antes de criar uma conexão, observe o seguinte:

• A URL e as credenciais são as únicas opções necessárias. Não insira credenciais na URL, pois logs ou erros podem expô-las. Use as opções de credencial dedicadas para o método de autenticação escolhido.
• Use externalOptionsAllowList para controlar quais opções de fonte de dados do Spark os usuários podem especificar no momento da consulta. Se não for especificado, a predefinição é 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Defina-a como uma cadeia de caracteres vazia para restringir os usuários apenas às opções definidas na conexão. Os usuários nunca podem especificar url ou host.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Clique Conecte-se e clique em Conexões.

3. Clique em Criar conexão.

4. Na página Noções básicas sobre conexão do assistente Configurar conexão, insira um Nome de conexão amigável.

5. Para o tipo de conexão, selecione JDBC.

6. (Opcional) Adicione um comentário.

7. Clique em Próximo.

8. Na página Detalhes da conexão , insira as seguintes propriedades de conexão:

   Propriedade	Description
   URL	A URL JDBC do banco de dados, no formulário jdbc:subprotocol:subname (por exemplo, jdbc:oracle:thin:@<host>:<port>:<SID>).
   dependências de Java	Os arquivos JAR do driver JDBC dos 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 de opções externas	Lista separada por vírgulas das opções de fonte de dados do Spark que os usuários de consulta podem especificar no momento da consulta. Usa dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions como padrão. Defina como um valor vazio para restringir os usuários apenas às opções definidas na conexão.
   Opções adicionais	Opções arbitrárias do driver JDBC passadas para o driver como pares de chave-valor. Use esta seção para definir as credenciais do banco de dados (por exemplo, chave user e chave password) e quaisquer outras propriedades específicas do driver. Alterne entre os modos de entrada UI e JSON, conforme necessário.

9. Clique em Criar conexão.

SQL

Use o CREATE CONNECTION comando SQL em um notebook 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 gerente de conexão pode adicionar à conexão todas as opções extras compatíveis com o driver JDBC. Por motivos de segurança, as opções definidas na conexão não podem ser substituídas no momento da consulta.

Etapa 3: Conceder o USE privilégio

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

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 de Lakehouse.

Etapa 4: Consultar a fonte de dados

Os usuários com o USE CONNECTION privilégio podem consultar a fonte de dados usando a conexão JDBC por meio do Spark ou da API sql de consultas remotas. Os usuários podem adicionar todas as opções de fonte de dados do Spark compatíveis com o driver JDBC e especificadas na externalOptionsAllowList conexão JDBC (por exemplo, neste caso: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Para exibir 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

Migration

Para migrar de cargas de trabalho existentes da API de Fonte de Dados do Spark, o Databricks recomenda fazer o seguinte:

• Remova a URL e as credenciais das opções na API de Fonte de Dados do Spark.
• Adicione o databricks.connection nas opções na API de Fonte de Dados do Spark.
• 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 especificadas consultando usuários.
• Na conexão, especifique as opções de fonte de dados que devem ser ajustadas ou modificadas pelos usuários no momento da externalOptionsAllowListconsulta no código da API da Fonte de Dados do Spark (por exemplo, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Limitações

API de Fonte de Dados do Spark

• A 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 conexão não podem ser usadas na API de Fonte de Dados em seu código no momento da consulta.
• Somente as opções especificadas no externalOptionsAllowList podem ser usadas consultando usuários.
• O limite de memória para o driver JDBC é de 400 MiB. Considere usar um menor fetchSize se o limite for atingido.

Support

• Não há suporte para fontes de dados do Spark.
• Lakeflow Spark Declarative Pipelines não é compatível.
• 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 de conexão precisa READ de acesso ao volume em que o JAR do driver JDBC está localizado.
• No modo de acesso dedicado (antigo modo de acesso de usuário único), você deve ser um proprietário ou um gerente da conexão para usá-lo.
• Não há suporte para certificados SSL.
• Não há suporte para catálogos estrangeiros com conexões JDBC.

Authentication

• Esse conector dá suporte à Credencial Estática e ao OAuth Machine-to-Machine. Ele não oferece suporte a credenciais do Unity Catalog nem a credenciais de serviço.

Rede

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

Conectividade de rede

A conectividade de rede do recurso de computação para o sistema de banco de dados de destino é necessária. Consulte as recomendações de rede para a Federação Lakehouse para obter diretrizes gerais de rede.

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

Azure Databricks VNets são configuradas para permitir apenas clusters Spark. Para se conectar a outra infraestrutura, coloque o sistema de banco de dados de destino em uma VNet diferente e use o emparelhamento VNet. Depois que o emparelhamento de VNet estiver estabelecido, verifique a conectividade usando a connectionTest UDF no cluster ou no armazém.

Se o Azure Databricks workspace e os sistemas de banco de dados de destino estiverem na mesma VNet, o Databricks recomendará um dos seguintes:

• Use a computação sem servidor.
• Configure seu banco de dados de destino para permitir o tráfego TCP e UDP pelas portas 80 e 443 e especifique essas portas na conexão.

Serverless

Ao usar sua conexão JDBC na computação sem servidor, você pode configurar um firewall para acesso de computação sem servidor ao sistema de banco de dados de destino adicionando IPs de saída a uma lista de permissões. Como alternativa, você pode configurar a conectividade privada.

Teste de conectividade

Para testar a conectividade entre a computação do Azure Databricks e seu sistema de banco de dados, use 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>');

perguntas frequentes

As perguntas frequentes a seguir abordam o comportamento do envio de predicados em conexões JDBC.

O JDBC dá suporte a pushdown de predicado?

Sim. Os filtros são aplicados diretamente ao banco de dados remoto por padrão, tanto pela API de fonte de dados do Spark (format('jdbc')) quanto pela remote_queryfunção SQL. Os predicados que podem ser propagados dependem do driver JDBC e do dialeto; portanto, execute EXPLAIN na sua consulta e inspecione o plano físico para confirmar quais filtros são propagados para a origem. Para a remote_query função SQL, você pode controlar pushdowns específicos (filtros, limites, deslocamentos e agregações) com opções como pushdown.filters.enabled; todas estão habilitadas por padrão.

O envio de predicados é distinto 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 na seleção da ordem das operações, independentemente de os predicados serem enviados.