Tutorial — conectar um banco PostgreSQL

Estado: o conector PostgreSQL é Disponível (maturidade GA-candidato): dá para cadastrar e usar hoje, sem liberação caso a caso. A construção de SQL e a sanitização de identificadores são provadas por teste. O que a extração real ainda depende é da credencial da sua origem e do ambiente de nuvem do workspace estar configurado — sem ele a execução falha com mensagem, em vez de fingir sucesso. Como todo o produto, ainda sem SLA público: custo/latência de nuvem = NÃO MEDIDO. Exemplos sintéticos.

Leia antes: Como os dados fluem · Catálogo de conectores.

O que é#

Conectar um banco PostgreSQL como fonte (modo pull, "Nós buscamos"): o Ingestia liga no seu banco com um usuário de leitura e extrai tabelas para a camada Bronze do seu workspace. Vale para PostgreSQL, e o mesmo fluxo cobre MySQL, SQL Server e Oracle (mudam só porta e alguns campos).

Para que serve#

Trazer dados operacionais (pedidos, clientes, estoque) do seu banco de produção para o datalake, sem exportar planilhas à mão, e mantê-los atualizados por agendamento.

Quando usar / quando não usar#

• Use quando: os dados moram num banco relacional acessível por rede (IP público com allowlist, Cloud SQL, VPN, ou via túnel SSH/bastion).
• Não use quando: você só tem arquivos soltos (use importar arquivo) ou os dados estão num SaaS com conector próprio (Omie, Bling, Meta Ads etc.).

Plano e permissões#

• Núcleo do produto · verificação de acesso (workspace ativo).
• Ação de carga passa pela chave de desligamento da capacidade execução de ingestão.
• Recomendado: um usuário de banco somente leitura dedicado ao Ingestia.

Pré-requisitos#

1. Host e porta do PostgreSQL (porta padrão 5432).
2. Database e, opcionalmente, o schema (default public).
3. Usuário e senha com permissão de SELECT nas tabelas desejadas.
4. Rota de rede — uma das opções:
   • IP público + allowlist: liberar o IP de saída do Ingestia no seu firewall.
   • Cloud SQL (IP/Proxy).
   • VPN (IP privado).
   • Túnel SSH (bastion): host/porta/usuário do bastion + chave privada SSH.
5. SSL definido (recomendado require ou superior).

Passo a passo#

1. No console, vá em ETL/ELT → Conexões e escolha PostgreSQL (categoria Bancos de dados).
2. Preencha os campos de conexão:
   • Host — ex.: db.suaempresa.example
   • Porta — 5432
   • Database — ex.: producao
   • Schema — ex.: public (opcional)
   • Usuário — ex.: ingestia_ro
   • Senha — a senha do usuário de leitura (é cifrada; nunca é exibida de novo)
3. Em SSL mode, escolha conforme sua política:
   • disable (sem SSL — evite), require, verify-ca ou verify-full.
4. Em Como conectamos (rede), escolha IP público + allowlist, Cloud SQL, VPN ou Túnel SSH. Se for SSH, preencha host/porta/usuário do bastion e cole a chave privada SSH.
5. Clique em Testar conexão. O Ingestia abre a conexão (e o túnel, se for o caso) e lista as tabelas acessíveis.
6. Com o teste OK, selecione as tabelas que quer ingerir e salve a fonte.

Exemplo (sintético)#

Engine: PostgreSQL
Host: db.suaempresa.example
Porta: 5432
Database: producao
Schema: public
Usuário: ingestia_ro
SSL mode: require
Rede: IP público + allowlist

Usuário de leitura de exemplo (execute no seu banco):

CREATE USER ingestia_ro WITH PASSWORD 'troque-esta-senha';
GRANT CONNECT ON DATABASE producao TO ingestia_ro;
GRANT USAGE ON SCHEMA public TO ingestia_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO ingestia_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO ingestia_ro;

Resultado esperado#

• Testar conexão retorna OK e a lista de tabelas (schema.tabela) aparece para seleção. O Ingestia lê o catálogo via information_schema.tables, excluindo os schemas de sistema, com teto de 2.000 tabelas listadas.
• Após uma carga, as linhas selecionadas aparecem na camada Bronze do seu workspace, prontas para o pipeline.

Limites e custos#

• Extração fragmentada (paginada): batchSize default 5.000 (100–50.000); maxRows default 200.000 (até 5.000.000).
• Teto duro de paginação anti-loop.
• A chamada ao seu banco não é cobrada pela plataforma; a carga Bronze consome processamento de carga no datalake (cobrável). Custo faturado real em BRL = NÃO MEDIDO.

Segurança#

• Nomes de schema/tabela/coluna são sanitizados (só [A-Za-z0-9_$]) antes de entrar no SQL — guarda anti-injeção.
• A senha (e a chave SSH) é cifrada (AES-256-GCM) e redigida em qualquer erro/log.
• Prefira usuário somente leitura; o Ingestia só executa SELECT.
• Escopo por workspace: as linhas vão para o Bronze do seu workspace, nunca de outro.

Erros comuns#

Diagnóstico#

• Use Testar conexão para isolar o problema (rede vs. credencial vs. permissão) — ele nunca lança; devolve OK + tabelas, ou uma mensagem de erro já redigida.
• Um administrador pode checar a saúde profunda do ambiente em GET /api/health?deep=1.

Relacionados#

• Conectar BigQuery
• Criar pipeline incremental por watermark
• Modos de carga (conceito)

Última revisão: 2026-09-08.