Capacidades
- Data Catalog. Cada tabela selecionada vira uma tabela na camada raw, com as colunas que ela tem no banco.
- Camada clean e Memory. O conector não traz transformação clean nem mapeamento de ontologia, porque as tabelas de cada banco são diferentes. Para limpar os dados e levá-los ao Memory, crie os modelos em Transformações no Console e mapeie as tabelas limpas na ontologia.
- Carga por tabela. Cada tabela tem o próprio modo de carga, a própria coluna de cursor e a própria chave primária.
Recursos disponíveis
As tabelas do conector só existem depois que ele lê o catálogo do seu banco. Não há lista fixa: cada tabela que você seleciona no Console vira um recurso.
O Console lista as tabelas de todos os schemas que o usuário do banco enxerga, exceto os schemas de sistema do PostgreSQL (
pg_catalog, information_schema e os que começam com pg_) e os schemas internos de extensões e plataformas como Supabase e TimescaleDB, por exemplo auth, storage, vault, cron e _timescaledb_internal. Views não aparecem na lista.
Para cada tabela, o Console mostra o número de colunas e sugere o modo de carga: incremental quando a tabela tem updated_at ou created_at, full refresh quando não tem. A chave primária sugerida é a da própria tabela; na falta dela, uma coluna chamada id ou terminada em _id.
Permissões (ACL)
Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.Como a fonte define acesso
No PostgreSQL, o acesso é dado a papéis (roles) porGRANT em bancos, schemas e tabelas. Onde há row-level security, uma política pode restringir as linhas que cada papel lê.
Como a Strattum traduz o acesso
O conector lê o banco com um único papel, o da connection string. Os grants e as políticas desse banco dizem o que esse papel pode ler, e não o que cada pessoa da sua empresa pode ver. Por isso o conector não grava permissão nas linhas.Quando a identidade não é encontrada
O conector não associa linhas a pessoas. A visibilidade depende apenas de Quem pode usar este conector.Quando a permissão é atualizada
A Strattum não lê permissões do banco. UmGRANT ou REVOKE feito no PostgreSQL só muda o que o papel da conexão consegue ler na próxima sincronização.
Pré-requisitos
- Um banco PostgreSQL que aceite conexões vindas da plataforma na porta configurada (padrão
5432). - Um usuário do banco só de leitura, com acesso aos schemas e às tabelas que você quer sincronizar.
- Se o banco está fora da sua rede privada, conexão com SSL.
- Acesso de administrador ao banco para criar esse usuário, ou alguém que o crie para você.
Autenticação e escopos
O conector se autentica com uma connection string no formatopostgresql://usuario:senha@host:5432/banco. As variantes postgresql+psycopg://, postgresql+psycopg2:// e postgresql+asyncpg:// também são aceitas e convertidas para o driver da plataforma. Parâmetros da URL, como sslmode=require, seguem o formato de URI de conexão do PostgreSQL (documentação).
1
Crie o usuário
Conectado com um usuário administrador, crie um usuário dedicado:
2
Conceda acesso ao banco e aos schemas
GRANT USAGE para cada schema além do public (documentação do GRANT).3
Conceda leitura nas tabelas
4
Libere as tabelas futuras
dono_das_tabelas pelo papel que cria as tabelas no schema. Sem FOR ROLE, o comando só vale para as tabelas que o próprio papel que o executou criar (documentação).5
Libere a rede
Em banco na nuvem (RDS, Cloud SQL, Supabase), libere os IPs de saída da plataforma no firewall ou no security group. Em banco próprio, confira também se o
pg_hba.conf aceita a conexão desse endereço e usuário (documentação).strattum_reader: o conector só copia as linhas que as políticas liberam para ele (documentação).
Configuração no Console
1
Preencha a conexão
Nome do Conector (Opcional): um nome para identificar esta instância. O padrão é
PostgreSQL.Escolha entre URL de Conexão e Campos.URL de Conexão (Obrigatório, quando selecionado): a connection string completa, como postgresql://usuario:senha@host:5432/banco?sslmode=require.Em Campos:- Host (Obrigatório): endereço do servidor.
- Porta (Opcional): o padrão é
5432. - Nome do Banco de Dados (Obrigatório).
- Schema (Opcional): não restringe a conexão. Os schemas são escolhidos na etapa de tabelas.
- Usuário (Obrigatório) e Senha (Obrigatório): as credenciais do usuário só de leitura.
- Usar SSL (Opcional): acrescenta
sslmode=requireà conexão.
2
Selecione as tabelas
Em Selecionar Tabelas, marque as tabelas que quer sincronizar. Todas começam desmarcadas, e é preciso marcar pelo menos uma. Use Filtrar tabelas… para buscar pelo nome.Para cada tabela marcada:
- Modo (Obrigatório):
incrementaloufull_refresh. - Cursor (Quando selecionado
incremental, obrigatório): a coluna que indica que a linha mudou. As colunas de data e hora aparecem primeiro, em Timestamp. - Chave Primária (Quando selecionado
incremental, obrigatório): a coluna que identifica a linha, usada para atualizar a linha em vez de duplicá-la. - Camada clean incremental (Opcional): veja “Limitações conhecidas”.
3
Defina a frequência
Frequência de Sincronização (Obrigatório): o recomendado é A cada 1h (recomendado). Também há opções prontas, de 10 minutos a semanal, e Personalizado, para informar uma Expressão Cron. Os horários são em UTC. A frequência vale para todas as tabelas selecionadas.
4
Configure acesso e visibilidade
Quem pode usar este conector (Obrigatório): “Todos os usuários” ou “Apenas times específicos”. Na segunda opção, selecione os Times com acesso.Comportamento dos dados: fica em “Aberto”, a única opção para esta fonte.
Como a sincronização funciona
O agendamento recomendado roda a cada hora. A cada execução, o conector testa a conexão comSELECT 1 e para a sincronização se ela falhar.
Depois, lê as tabelas selecionadas, uma de cada vez. Cada tabela é lida por um cursor no servidor, em lotes de 1.000 linhas.
Full refresh. O conector lê a tabela inteira e substitui a tabela raw anterior. Linhas apagadas no banco somem do Data Catalog.
Incremental. O conector guarda o maior valor da coluna de cursor já lido. Na execução seguinte, lê só as linhas com cursor maior ou igual a esse valor, em ordem crescente, e atualiza a tabela raw pela chave primária. O “maior ou igual” relê as linhas da fronteira, para não perder uma linha que chegou com o mesmo valor de cursor depois da leitura anterior. Como a atualização é pela chave primária, a releitura não duplica linhas. A coluna de cursor pode ser de data e hora ou numérica, como um id que só cresce.
Primeira sincronização. A primeira execução de uma instância nova é uma amostra: as tabelas em full refresh param em 1.000 linhas. As tabelas em incremental são lidas inteiras já na primeira vez. A partir da segunda execução, tudo é lido por completo.
Camada clean. Depois da cópia, a plataforma reconstrói os modelos clean que leem estas tabelas, se você os criou em Transformações. Quando todas as tabelas estão em incremental e nenhuma linha mudou, essa etapa é pulada.
Falhas. O teste de conexão é repetido até 2 vezes (após 30 e 60 segundos). A leitura de cada tabela é repetida até 3 vezes (após 30, 60 e 120 segundos).
API da fonte
O conector não usa API HTTP. Ele se conecta direto ao PostgreSQL e executa estas consultas:
Rate limits. Limite da fonte: o PostgreSQL não tem limite de requisições. O limite é o número de conexões simultâneas do servidor,
max_connections, que por padrão costuma ser 100 (documentação).
Comportamento do conector: por padrão, ele lê uma tabela de cada vez, com uma conexão por leitura, e busca 1.000 linhas por lote. O teste de conexão do Console desiste depois de 10 segundos sem resposta. Em caso de erro, a leitura da tabela é repetida conforme descrito em “Como a sincronização funciona”.
Referência oficial: https://www.postgresql.org/docs/current/
Limitações conhecidas
- O conector não traz transformação clean nem mapeamento de ontologia. Sem modelos em Transformações, os dados ficam só na camada raw e não chegam ao Memory.
- Permissões do banco (grants, papéis e row-level security) não são levadas para a Strattum. Todos que podem usar o conector veem todas as linhas copiadas.
- Views não aparecem na lista de tabelas do Console. Só tabelas podem ser sincronizadas.
- Em incremental, linha apagada no banco continua no Data Catalog. Use full refresh para remover.
- Em incremental, linha com a coluna de cursor vazia (
NULL) só é lida na primeira sincronização. Depois disso, ela não é mais relida, mesmo que mude. - Em incremental, uma alteração que não atualiza a coluna de cursor não é percebida.
- A opção Camada clean incremental é gravada, mas a construção da camada clean não a usa hoje: os modelos clean são reconstruídos inteiros a cada execução.
- A primeira sincronização copia no máximo 1.000 linhas de cada tabela em full refresh. A cópia completa acontece a partir da segunda execução.
- Schema cujo nome contém dois sublinhados seguidos (
__) não é lido corretamente, porque o conector usa__para separar schema e tabela. - A sincronização usa as credenciais da instância PostgreSQL criada por último. Mantenha uma instância por ambiente.
Troubleshooting
Próximos passos
Data Catalog
Encontre as tabelas copiadas do PostgreSQL na camada raw.
Memory
Veja como as tabelas limpas viram entidades e relações no grafo.
Desenvolvimento local
Desenvolvimento local
O flow Crie o conector pelo Console local para gravar a credencial no registro antes de disparar o flow.
postgres_sync não lê a connection string do .env. Ele busca a credencial POSTGRES_CLIENT_URL no registro de conectores, que o Console preenche ao criar o conector. Com SECRET_BACKEND=json_file, o padrão do Starter, o registro fica em secrets/connector_registry.json. Veja Desenvolvimento local.