Leia antes:
../conectores.md(mapa de estados) efichas.md(índice das fichas).
What it is#
Connects to the Postgres of your Supabase project (direct connection or session-mode pooler, with TLS) and extracts tables on a schedule. Supports incremental load by watermark.
Supported ingestion modes:
- Nós buscamos — Nós buscamos os dados na sua fonte.
What it's for#
Bring data from Supabase into your datalake and make it available to the Bronze/Silver/Gold layers, BI models and the natural-language question wizard.
When to use / when not to use#
Use when you need to consolidate this source into the datalake on a schedule, with isolation by workspace.
Avoid unnecessary full loads on large tables: prefer incremental load by watermark (see Limits and the incremental guide).
Plan and permissions#
- Plan: core product (connectors are part of all plans; the limit is the number of sources allowed by the plan).
- Access: requires an active workspace — with the subscription past due, suspended or cancelled, the run is blocked.
- Shutdown: the ingestion run can be temporarily disabled (maintenance or incident). When that happens, the screen indicates that the feature is unavailable at the moment.
Prerequisites#
- A read-only user in the database, with access to the desired schema/tables.
- Network: choose how we reach the database — public IP + allowlist, SSH tunnel (bastion), Cloud SQL or VPN.
- Allow two networks at the source: the application server (where Test connection runs from) and the pipeline runner (where the scheduled extraction runs from), which has a different outbound IP.
Credentials#
Sensitive fields. They are encrypted (AES-256-GCM) and are never stored in the connection config, the pipeline definition, the export or the DAG. By default the encrypted value is kept in the database; moving this connection's credential to an external credential vault is an explicit choice, made per connection after saving — see ../../administracao/credenciais-e-rotacao.md.
- Password (
password) — Stored encrypted. After saving, no one can see it again — not even you. - SSH private key (
sshPrivateKey)
Secrets are never re-displayed and are redacted in any error/log (raw token, URL-encoded and in JSON).
Form fields#
| Campo | Rótulo | Tipo | Obrigatório | Observação |
|---|---|---|---|---|
host | Endereço do servidor | texto | sim | Nome ou IP do servidor do banco. Quem cuida do seu sistema (TI ou fornecedor do ERP) sabe informar. |
port | Porta | número | sim | padrão: 5432; Já vem com a porta padrão (5432). Só mude se o seu TI disser que é outra. |
database | Nome do banco | texto | sim | O nome do banco de dados dentro do servidor. |
schema | Schema | texto | não | Opcional. Deixe vazio para ver todas as tabelas que o usuário enxerga. |
user | Usuário | texto | sim | Prefira um usuário só de LEITURA, criado para o BI. |
password 🔒 | Senha | senha/segredo | sim | segredo (cifrado; cofre externo opcional); Guardada cifrada. Depois de salva, ninguém consegue vê-la de novo — nem você. |
sslmode | Segurança da conexão (SSL) | seleção | não | padrão: require; opções: disable / require / verify-ca / verify-full; Deixe em “require” (conexão protegida). Só mude se o seu TI pedir. |
network | Como chegamos ao banco | seleção | não | padrão: direct; opções: direct / ssh / cloudsql / vpn; Na maioria dos casos é “direto pela internet”. Use túnel SSH se o banco só aceita acesso pela rede interna. |
sshHost | Host do bastion (SSH) | texto | não | aparece quando network = ssh |
sshPort | Porta do bastion | número | não | padrão: 22; aparece quando network = ssh |
sshUser | Usuário do bastion | texto | não | aparece quando network = ssh |
sshPrivateKey 🔒 | Chave privada SSH | senha/segredo | não | segredo (cifrado; cofre externo opcional); aparece quando network = ssh |
Step by step#
- No menu Dados → Conexões, use Nova conexão.
- Escolha Supabase no catálogo.
- Preencha os campos do formulário (veja a tabela acima).
- Use Testar conexão. The result is shown broken down into Conectividade, Autenticação and Listagem/leitura — each with OK, Failed, Not applicable or Not tested. A capability with no test of its own for this connector shows as Not applicable, and Not applicable never counts as success.
- Use Salvar conexão. Salvar NÃO inicia ingestão nenhuma.
- No cartão da conexão, use Montar extração (ou vá em Orquestração → Pipelines e use Conectar fonte). O pipeline aponta para a connection salva — a credential não é copiada.
- Na revisão, Publicar (agenda desligada) cria a versão 1 sem executar nada. Depois, Ativar agenda e Executar agora são ações separadas.
Example — connection test#
Example configuration (all values are fictitious; secrets appear masked):
# Exemplo sintético (valores fictícios — não são credenciais reais)
host = db.exemplo.invalid
port = 5432
database = vendas
schema = public
user = leitura_bi
password = •••••• (cifrado — nunca exibido)
sslmode = require
network = directExpected result#
Testar conexão returns the list of discovered tables/resources. After the first load, rows appear in the Bronze layer of your workspace, ready for the pipeline.
Limits and costs#
- Pagination: hard cap per run (default 10,000 pages / 5,000,000 rows); anti-loop guard.
- Incremental by watermark: append/keyset by key-column. Not CDC — does not capture deletes or UPDATEs outside the watermark window. True CDC (WAL/redo/binlog) is on the Roadmap.
- Estimated volume: ~5 GB/month (catalog estimate, not measurement).
- Cost: the extraction itself is not billed by the platform; the Bronze load consumes datalake processing (billable).
Security#
- Scope by workspace: each customer reads and writes only to their own datalake (
<prefix>_bronze/_silver/_gold); there is never leakage between workspaces. - Secrets encrypted: sensitive material is encrypted with AES-256-GCM before being stored. The external credential vault is optional and enabled per connection; without it, the encrypted value remains in the database. Changing the value here DOES NOT revoke the credential at the source.
- Redaction: every error/log goes through secret redaction (raw, URL-encoded and in JSON).
- Production does not fake: a path that would fall into a mock triggers the production guard (explicit failure instead of simulating success).
Common errors#
- Connection refused / timeout — host, port or network rule (allowlist/SSH/VPN) incorrect. Check the chosen network mode in How we reach the database. Remember there are two networks: the application server (where Test connection runs from) and the pipeline runner (where the scheduled extraction runs from), with different outbound IPs.
- Authentication failed — invalid user/password or user without read permission on the schema.
- SSL/handshake — adjust Connection security (SSL) (
sslmode:disable,require,verify-ca,verify-full) according to the server's requirements. - Large table/query — extraction respects the pages/rows cap; use incremental load by watermark to reduce volume.
Troubleshooting#
- Use Testar conexão to isolate credential/network issues before scheduling.
- Monitor runs in the observabilidade por conector (error rate, p50/p95, freshness).
- A schema change at the source is signaled by schema drift (new column = info; removed column/type changed = attention).
Related#
../conectores.md— catálogo de conectores por estado../ingestao-incremental-backfill.md— full, incremental por watermark, backfill e checkpoint../pipeline-medalhao.md— camadas Bronze/Silver/Gold e qualidade../agendamento-retry-dlq.md— agendamento, retry/backoff e DLQ../custo-limites-seguranca.md— custo, tetos e segurança por workspace
Última revisão: 2026-10-04. Ficha gerada automaticamente do catálogo de conectores do produto.