postgresql¶

destino

grava dados de um workflow em um banco sql relacional: postgresql, mysql, sql server ou oracle. suporta três modos de escrita: append, replace e upsert.

casos de uso¶

popular tabelas dimensão e fato em um data warehouse relacional
sincronizar dados processados de volta para um sistema operacional
fazer carga incremental com upsert por chave de negócio

bancos suportados¶

os mesmos suportados na fonte postgresql: postgresql, mysql, sql server, oracle.

configuração¶

campo	tipo	obrigatório	descrição
`credential_id`	uuid	sim	id da conexão em conexões
`table`	string	sim	tabela de destino
`schema`	string	não	schema da tabela · padrão: `public` (postgres)
`write_mode`	enum	não	`append`, `replace`, `upsert` · padrão: `append`
`upsert_keys`	lista	sim*	colunas usadas como chave de upsert
`auto_create_table`	bool	não	cria a tabela se não existir · padrão: `false`

*obrigatório quando write_mode = upsert.

modos de escrita¶

append¶

insere todos os registros do upstream como novas linhas. não verifica duplicatas.

{
  "credential_id": "uuid",
  "table": "logs_eventos",
  "write_mode": "append"
}

replace¶

apaga todos os registros existentes na tabela e reinsere os dados do upstream. equivale a TRUNCATE + INSERT.

{
  "credential_id": "uuid",
  "table": "dim_produtos",
  "write_mode": "replace"
}

replace apaga tudo

use com cuidado em tabelas de produção. prefira upsert quando quiser manter histórico ou dados não contemplados na extração atual.

upsert¶

atualiza registros com chave coincidente e insere os novos. usa INSERT ... ON CONFLICT DO UPDATE (postgres) ou equivalente.

{
  "credential_id": "uuid",
  "table": "clientes",
  "schema": "dw",
  "write_mode": "upsert",
  "upsert_keys": ["cliente_id"]
}

upsert com chave composta:

{
  "credential_id": "uuid",
  "table": "fato_vendas",
  "write_mode": "upsert",
  "upsert_keys": ["data_venda", "loja_id", "produto_id"]
}

criação automática de tabela¶

quando auto_create_table = true, o conector infere o schema a partir dos dados do duckdb e cria a tabela se ela não existir:

{
  "credential_id": "uuid",
  "table": "clientes_novo",
  "write_mode": "append",
  "auto_create_table": true
}

tipos de dados

a inferência de tipos segue o mapeamento duckdb → sql. revise os tipos criados automaticamente antes de usar em produção — especialmente para colunas de data e valores monetários.

fluxo de execução¶

duckdb (tabela upstream)
     ↓ SELECT * FROM upstream_table
dataframe pandas
     ↓ to_sql() / bulk insert
tabela destino no banco relacional

branch developer¶

em pipelines no branch developer, este conector é bloqueado. as escritas são redirecionadas para o lakehouse interno de staging. isso evita modificações acidentais em bancos de produção durante o desenvolvimento.