JDBC

validado

Use JDBC para bancos de dados relacionais quando o runtime do Spark tiver o driver, a rota de rede e as credenciais necessárias para ler a partir da origem. ContractForge constrói o contrato do leitor, registra metadados seguros e permite que os modos de gravação lidem com a semântica de destino.

Quando usar

Bancos de dados operacionais

Extração relacional

Use JDBC para PostgreSQL, MySQL, SQL Server, Oracle e serviços gerenciados compatíveis.

Cargas incrementais

Colunas de marca d'água

Combine predicados de origem, marcas d’água ContractForge e desduplicação determinística antes da mesclagem.

Mesas grandes

Leituras particionadas

Use colunas de partição, limites, partições e tamanho de busca para evitar extração de thread único.

Bancos de dados em nuvem

Rede primeiro

Valide rotas, firewalls, grupos de segurança, drivers e credenciais antes de ajustar o contrato.

Requisitos de runtime

Exigência	Detalhes
Driver JDBC	O driver de banco de dados correspondente deve estar instalado ou disponível para o Spark.
Rota de rede	O runtime deve atingir o host e a porta do banco de dados.
Credenciais	Use segredos do Databricks ou identidade gerenciada em runtime. Não confirme credenciais de banco de dados em contratos.
Permissões de origem	O usuário de origem deve ter permissão para ler a tabela/consulta selecionada e os metadados necessários ao driver.

Databricks serverless

O JDBC em serverless só é viável quando três camadas estão disponíveis ao mesmo tempo: um driver JDBC compatível, uma rota de rede para o endpoint do banco de dados e credenciais que o leitor Spark pode usar. ContractForge pode construir o contrato do conector e gerar tokens RDS IAM, mas não pode ignorar rotas de rede ausentes ou suporte de driver ausente.

Preocupação	O que verificar	Correção típica
Motorista	No suitable driver, classe não encontrada ou pacote de conector não suportado.	Use uma política de runtime, uma biblioteca instalada ou um tipo de cluster que exponha o driver do banco de dados.
Rede	O DNS é resolvido, mas a conexão TCP atinge o tempo limite ou o banco de dados rejeita a origem do runtime.	Configure regras de acesso público, lista de permissões de firewall, PrivateLink, emparelhamento de VPC/VNet ou política de rede do espaço de trabalho.
Autenticação	A senha/token funciona fora do Spark, mas falha no trabalho.	Valide nomes secretos, expiração de token, opções de SSL, política IAM e concessões de usuários de banco de dados.
Forma de extração	As leituras são bem-sucedidas, mas são lentas ou criam conflitos de mesclagem.	Adicione predicados, particionamento, tamanho de busca, desduplicação determinística e regras importantes de qualidade.

Aliases suportados

Conector	Motorista típico	Notas
jdbc	Fornecido pelo usuário	Leitor genérico Spark JDBC.
postgres	org.postgresql.Driver	Postgres, Supabase, Aurora PostgreSQL e RDS PostgreSQL.
mysql	Conector MySQL/J	Requer driver de runtime correspondente.
sqlserver	Driver JDBC da Microsoft	Use opções de conexão criptografada conforme necessário.
oracle	Driver JDBC Oracle	O licenciamento/distribuição de drivers geralmente é feito pela plataforma.

Autenticação básica

source:
  type: connector
  connector: postgres
  options:
    url: "{{ secret:crm/postgres_url }}"
    dbtable: public.orders
    driver: org.postgresql.Driver
  auth:
    type: basic
    username: "{{ secret:crm/postgres_user }}"
    password: "{{ secret:crm/postgres_password }}"
  read:
    fetchsize: 10000

target:
  catalog: main
  schema: bronze_crm
  table: b_orders_jdbc

layer: bronze
mode: append
schema_policy: additive_only

Padrão SCD1 incremental

Para tabelas de estado atual, combine marca d'água de origem, desduplicação determinística e portas de qualidade chave antes de MERGE.

source:
  type: connector
  connector: postgres
  options:
    url: "{{ secret:crm/postgres_url }}"
    dbtable: public.orders
    driver: org.postgresql.Driver
  auth:
    type: basic
    username: "{{ secret:crm/postgres_user }}"
    password: "{{ secret:crm/postgres_password }}"
  incremental:
    watermark_column: updated_at
  read:
    fetchsize: 10000
    predicate: "updated_at >= timestamp '2026-01-01'"

target:
  catalog: main
  schema: silver_sales
  table: s_orders

layer: silver
mode: upsert
merge_keys: [order_id]
watermark_columns: [updated_at]
transform:
  deduplicate:
    keys: [order_id]
    order_by: updated_at DESC NULLS LAST
quality_rules:
  not_null: [order_id]
  unique_key: [order_id]

Leituras particionadas

Use particionamento JDBC para tabelas grandes. O particionamento só funciona bem quando a coluna de partição é numérica/semelhante a data, razoavelmente distribuída e delimitada corretamente.

source:
  type: connector
  connector: postgres
  options:
    url: "{{ secret:crm/postgres_url }}"
    dbtable: public.order_items
    driver: org.postgresql.Driver
  auth:
    type: basic
    username: "{{ secret:crm/postgres_user }}"
    password: "{{ secret:crm/postgres_password }}"
  read:
    partition_column: order_item_id
    lower_bound: 1
    upper_bound: 50000000
    num_partitions: 16
    fetchsize: 20000

Limites não são filtros

Os limites do Spark JDBC definem o avanço da partição. Eles não restringem necessariamente o resultado definido por si próprios. Use predicados ou subconsultas quando precisar de filtragem na origem.

Padrão de consulta e pushdown

Use query ou um estilo de subconsulta dbtable quando a extração precisar de um predicado revisado ou uma junção que pertença ao sistema de origem. Mantenha a grande transformação dos negócios fora do conector.

source:
  type: connector
  connector: jdbc
  options:
    url: "{{ secret:erp/jdbc_url }}"
    query: |
      SELECT id, updated_at, status, total_amount
      FROM sales.orders
      WHERE updated_at >= TIMESTAMP '2026-01-01'
        AND status IN ('closed', 'cancelled')
    driver: org.postgresql.Driver
  auth:
    type: basic
    username: "{{ secret:erp/user }}"
    password: "{{ secret:erp/password }}"

Padrão de comparação de hash SCD1

Use hash diff quando o destino precisar anexar apenas linhas cujo conteúdo comercial foi alterado em comparação com o estado de destino mais recente.

target:
  catalog: main
  schema: silver_sales
  table: s_product_prices

layer: silver
mode: hash_diff_upsert
hash_keys: [product_id]
dedup_order_expr: updated_at DESC NULLS LAST
quality_rules:
  not_null: [product_id]
  unique_key: [product_id]

Último estado determinístico

A diferença de hash depende de uma comparação confiável do estado mais recente. Use a ordem de desduplicação explícita quando a origem puder conter diversas versões por chave.

Amazon RDS/Aurora IAM

Para RDS/Aurora PostgreSQL com autenticação IAM, ContractForge pode gerar um token de autenticação no driver Python. O runtime ainda precisa de acessibilidade de rede e de um driver JDBC compatível.

source:
  type: connector
  connector: postgres
  options:
    host: mydb.abc123.us-east-1.rds.amazonaws.com
    port: 5432
    database: app
    dbtable: public.orders
    driver: org.postgresql.Driver
  auth:
    type: rds_iam
    username: "{{ secret:contractforge-aws/rds_username }}"
    region: us-east-1
    credential_provider: default_chain
    sslmode: require

Provedor de credenciais	Usar
explicit	Use chave de acesso, chave secreta e token de sessão opcional de segredos.
env	Use credenciais da AWS já disponíveis como variáveis ​​de ambiente.
default_chain	Use a cadeia de credenciais padrão do botocore. Requer contractforge[aws] ou botocore fornecido em runtime.

Pré-requisitos de rede

As falhas de JDBC geralmente são problemas de plataforma/rede, não de contrato. Valide o caminho antes de ajustar o contrato.

• O nome do anfitrião da base de dados deve ser resolvido a partir do runtime do Databricks.
• Grupos de segurança, firewalls e listas de permissões de bancos de dados devem permitir o IP de origem do runtime ou a rota privada.
• Os bancos de dados privados geralmente precisam de peering de VPC, PrivateLink, VPN ou rede na mesma nuvem.
• O driver JDBC deve estar instalado ou disponível no caminho de classe do runtime.
• Os tempos de execução serverless podem restringir drivers personalizados ou rotas de rede dependendo da configuração do espaço de trabalho.

Metadados operacionais

Os metadados de origem JDBC são editados antes da persistência. Use-o para verificar opções de conector, tipo de autenticação, particionamento e origem sem expor credenciais.

SELECT
  run_id,
  source_connector,
  source_provider,
  source_options_json,
  source_auth_redacted_json,
  source_read_redacted_json,
  source_metrics_json
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector IN ('jdbc', 'postgres', 'mysql', 'sqlserver', 'oracle')
ORDER BY started_at_utc DESC;

Problemas comuns

Sintoma	Causa provável	Ação
Nenhum driver adequado	O jar JDBC não está instalado.	Instale o driver correspondente em ambiente cluster/serverless.
Tempo limite de conexão	Nenhuma rota de rede para o banco de dados.	Corrija VPC, peering, PrivateLink, firewall ou regras de acesso público.
Falha na autenticação	Segredo errado, senha/token expirado ou problema de política IAM.	Valide primeiro as credenciais fora do ContractForge.
Extração lenta	Partição JDBC única ou nenhum pushdown de predicado.	Adicione particionamento, tamanho de busca e predicados de origem.
Erro de chave duplicada MERGE	A origem possui vários registros por chave.	Adicione transform.deduplicate e regras-chave de qualidade.