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

Conexão JDBC

nota

Este recurso está em Pré-visualização Pública para Databricks Runtime 18.1 e DBSQL 2025.40 e versões superiores. Para SQL Warehouse, você também precisa ativar a opção "Habilitar rede para cargas de trabalho isoladas" na versão prévia SQL Warehouse sem servidor .

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 distribui as consultas Spark para otimizar o desempenho das consultas.
nota

A federação de consultas é compatível com muitos bancos de dados populares, incluindo Oracle, MySQL, PostgreSQL, SQL Server e Snowflake. Se o seu banco de dados for compatível, a Databricks recomenda o uso de federação de consultas em vez de uma conexão JDBC. Consulte a Lakehouse Federation para obter a lista completa de bancos de dados suportados.

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 enviar as consultas SQL de origem para baixo com a opção Spark query .

Por que usar JDBC versus PySpark fonte de dados?​

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ê só o utiliza em cargas de trabalho de Notebook ou PySpark .
  • Se você deseja implementar uma lógica de particionamento personalizada.

Nem JDBC nem PySpark fonte de dados 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 ter o privilégio CREATE CONNECTION no metastore anexado ao workspace.
  • CREATE ou MANAGE acesso a um volume Unity Catalog pelo criador da conexão.
  • Acesso ao volume pelo usuário que consulta a conexão.
  • Permissões adicionais são especificadas em cada seção baseada em tarefas que se segue.

Métodos de autenticação​

Credencial Estática

A autenticação de credencial estática armazena as credenciais diretamente na conexão: por exemplo, um nome de usuário e senha, uma API key ou qualquer outro campo de credencial aceito pelo driver JDBC de destino. As credenciais são passadas para o Driver JDBC conforme estão quando a conexão é usada.

OAuth máquina para máquina

info

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

A autenticação OAuth Machine-to-Machine (M2M) é usada quando dois sistemas ou aplicativos se comunicam sem o envolvimento direto do usuário. Tokens são emitidos para um cliente de máquina registrado, que utiliza as suas próprias credenciais para autenticação. Esse método de autenticação é ideal para comunicação de serviço a serviço, microsserviços e tarefas de automação em que nenhum contexto de usuário é necessário.

Quando a conexão JDBC usa OAuth M2M, o Unity Catalog troca as credenciais do cliente no endpoint de tokens configurado e passa apenas o access token de curta duração resultante para o driver JDBC usando o parâmetro de token do driver.

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 consultarem 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​

Uma conexão JDBC é um objeto protegível no Unity Catalog. Ela especifica o driver JDBC, o caminho da URL, as credenciais para acessar um sistema de banco de dados externo e as opções permitidas que o usuário consultante pode especificar. Para criar uma conexão, use o Catalog Explorer ou o comando CREATE CONNECTION do SQL em um Notebook do Databricks ou no editor de consultas SQL do Databricks. Consulte métodos de autenticação para os métodos de autenticação compatíveis.

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.

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

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

  1. No seu workspace Databricks , clique em Ícone de dados. Catálogo .

  2. Clique em Ícone de plugue. **Conectar**, e então clique em **Conexões**.

  3. Clique em Criar conexão .

  4. Na página "Informações básicas de conexão" do assistente de configuração de conexão , insira um nome de conexão amigável.

  5. Para **Tipo de conexão**, selecione **JDBC**.

  6. (Opcional) Adicione um comentário.

  7. Clique em Avançar .

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

Propriedade

Descrição

URL

A URL JDBC para seu banco de dados, no formato jdbc:subprotocol:subname (por exemplo, jdbc:oracle:thin:@<host>:<port>:<SID>).

Dependências Java

Os arquivos JAR do driver JDBC dos volumes do Unity Catalog. Clique em Adicionar dependência JAR para adicionar cada JAR (por exemplo, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).

Lista de opções externas permitidas

Lista separada por vírgulas de opções de fonte de dados Spark que os usuários podem especificar no momento da consulta. O padrão é dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. Defina um valor vazio para restringir os usuários apenas às opções definidas na conexão.

Opções Adicionais

Opções arbitrárias de driver JDBC passadas para o driver como pares key-value. Use esta seção para definir credenciais de banco de dados (por exemplo, key user e key password) e quaisquer outras propriedades específicas do driver. Alterne entre os modos de entrada **IU** e **JSON** conforme necessário.

  1. Clique em Criar conexão .

OAuth Máquina para Máquina (Beta)

info

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

Quando a visualização jdbc_oauth_m2m_connector é habilitada em seu workspace, o campo Tipo de autenticação aparece na página Noções básicas de conexão com as opções Credencial estática e OAuth máquina para máquina . Para criar uma conexão JDBC OAuth M2M:

  1. Na página Noções básicas de conexão , defina Tipo de autenticação como OAuth máquina a máquina .

  2. Clique em Avançar .

  3. Na página **Detalhes da conexão**, insira as seguintes propriedades além de **URL** e **dependências Java**:

Propriedade

Descrição

ID do cliente

O ID do cliente OAuth emitido para o aplicativo.

Segredo do cliente

O segredo do cliente OAuth emitido para o aplicativo.

Escopo OAuth

Escopo a ser solicitado durante a troca de tokens. Expresso como uma lista de strings sensíveis a maiúsculas e minúsculas.

Endpoint de token

O endpoint de token do OAuth 2.0 usado para trocar as credenciais do cliente por um access token. Geralmente no formato https://authorization-server.com/oauth/token.

Método de troca de credenciais OAuth

Como as credenciais do cliente são passadas para o endpoint do token:

  • **header_and_body** — as credenciais são enviadas tanto no Authorization cabeçalho quanto no corpo da solicitação (default).
  • body_only — as credenciais são enviadas somente no corpo da solicitação.
  • header_only — as credenciais são enviadas apenas no cabeçalho Authorization.

Nome do parâmetro de token JDBC

A propriedade **KEY** exigida pelo driver JDBC de destino para aceitar o access token OAuth. A Databricks preenche dinamicamente este parâmetro **VALUE** com um access token OAuth válido gerado. **KEYs** access_tokentípicos:, oauthToken passwordou. Consulte a documentação do seu driver JDBC para o nome correto do parâmetro **KEY**.

  1. Clique em Criar conexão .

O proprietário ou administrador da conexão pode adicionar à conexão quaisquer opções extras 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.

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 através Spark ou da 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 source 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 especificadas pelos usuários que realizam 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.
  • O limite de memória para o driver JDBC é de 400 MiB. Considere usar um fetchSize menor se o limite for atingido.

Apoiar​

  • Fontes de dados Spark não são suportadas.
  • 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 da conexão precisa de acesso READ ao volume onde o JAR do driver JDBC está localizado.
  • No modo de acesso dedicado (anteriormente modo de acesso de usuário único), você precisa ser o proprietário ou o administrador da conexão para usá-la.
  • Certificados SSL não são suportados.
  • Catálogos externos não são suportados com conexões JDBC.

Autenticação​

  • Este conector oferece suporte a Credencial Estática e OAuth máquina para máquina. Não oferece suporte a credenciais do Unity Catalog 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>');

Perguntas frequentes​

As seguintes perguntas frequentes abrangem o comportamento de predicate pushdown para conexões JDBC.

O JDBC oferece suporte ao predicate pushdown?​

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

O pushdown de predicado é distinto de expor estatísticas de tabela ao otimizador de query. As fontes de dados JDBC e PySpark não expõem estatísticas ao otimizador de query para ajudar a selecionar a ordem das operações, independentemente de os predicados serem enviados.

Nesta página