> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # PostgreSQL > Copia as tabelas que você escolher de um banco PostgreSQL para a camada raw do Data Catalog, com carga incremental ou completa definida tabela por tabela. O conector PostgreSQL lê as tabelas que você seleciona num banco PostgreSQL e grava cada uma como uma tabela na camada raw do Data Catalog. Você escolhe, tabela por tabela, se a carga é incremental ou completa. | | | | - | - | | **Status** | Disponível | | **Conteúdo** | Registros | | **Autenticação** | Connection string (usuário e senha do banco) | | **Permissões** | Sem permissão por item | | **Sincronização** | Incremental e full refresh, por recurso | | **Última revisão** | 24/09/2026 | ## 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. | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `{schema}__{table}` | Uma tabela do banco, com todas as colunas e linhas. O nome junta o schema e a tabela, como `public__customers` para `public.customers` | Incremental ou full refresh, escolhido por tabela | A coluna que você escolher, por tabela | Catálogo | Não | 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) por `GRANT` 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. Um `GRANT` 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 formato `postgresql://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](https://www.postgresql.org/docs/current/libpq-connect.html)). | Escopo ou permissão | Para quê | | - | - | | `CONNECT` no banco | Abrir a conexão | | `USAGE` em cada schema | Enxergar as tabelas do schema na lista do Console e ler seu catálogo | | `SELECT` em cada tabela | Ler as linhas na sincronização | **1. Crie o usuário** Conectado com um usuário administrador, crie um usuário dedicado: ```sql theme={null} CREATE USER strattum_reader WITH PASSWORD 'senha_segura'; ``` **2. Conceda acesso ao banco e aos schemas** ```sql theme={null} GRANT CONNECT ON DATABASE nome_do_banco TO strattum_reader; GRANT USAGE ON SCHEMA public TO strattum_reader; ``` Repita o `GRANT USAGE` para cada schema além do `public` ([documentação do GRANT](https://www.postgresql.org/docs/current/sql-grant.html)). **3. Conceda leitura nas tabelas** ```sql theme={null} GRANT SELECT ON ALL TABLES IN SCHEMA public TO strattum_reader; ``` O comando vale para as tabelas que já existem. **4. Libere as tabelas futuras** ```sql theme={null} ALTER DEFAULT PRIVILEGES FOR ROLE dono_das_tabelas IN SCHEMA public GRANT SELECT ON TABLES TO strattum_reader; ``` Troque `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](https://www.postgresql.org/docs/current/sql-alterdefaultprivileges.html)). **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](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)). Se o banco usa row-level security, as políticas se aplicam ao `strattum_reader`: o conector só copia as linhas que as políticas liberam para ele ([documentação](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)). ## 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. Clique em **Testar Conexão**. O Console só avança depois de um teste bem-sucedido e, logo em seguida, lista as tabelas do banco. **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): `incremental` ou `full_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 com `SELECT 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: | Consulta | Usado para | Recurso | | - | - | - | | `SELECT 1` | Testar a conexão, no Console e no início de cada sincronização | Nenhum | | Catálogo do sistema (`pg_namespace`, `pg_class`), lido pelo SQLAlchemy | Listar no Console os schemas, as tabelas, as colunas e as chaves primárias e estrangeiras | `{schema}__{table}` | | `information_schema.columns` | Descobrir tabelas e colunas na descoberta do próprio conector | `{schema}__{table}` | | `pg_class` (`reltuples`) | Estimar o número de linhas de cada tabela na lista do Console | `{schema}__{table}` | | `SELECT * FROM "schema"."tabela"` | Ler a tabela inteira em full refresh | `{schema}__{table}` | | `SELECT * FROM "schema"."tabela" WHERE "cursor" >= :last_value ORDER BY "cursor" ASC` | Ler só as linhas novas ou alteradas em incremental | `{schema}__{table}` | **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](https://www.postgresql.org/docs/current/runtime-config-connection.html)). 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/](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 | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | "Informe a URL de conexão antes de testar" | O campo **URL de Conexão** está vazio | Preencha a connection string | | "Preencha host, banco, usuário e senha antes de testar" | Falta um campo obrigatório no modo **Campos** | Preencha **Host**, **Nome do Banco de Dados**, **Usuário** e **Senha** | | "Erro ao conectar ao PostgreSQL: ..." | O banco recusou a conexão. O texto depois dos dois-pontos é a mensagem do PostgreSQL: senha errada, host inacessível, porta fechada, SSL exigido ou `pg_hba.conf` sem regra para esse endereço | Corrija conforme a mensagem. Para problemas de rede, confira firewall, porta e `pg_hba.conf` | | "Nenhuma tabela encontrada no banco." | O usuário não tem `USAGE` em nenhum schema, ou os schemas visíveis só têm views | Conceda `USAGE` e `SELECT` como em "Autenticação e escopos" | | "Complete cursor e chave primária" | Uma tabela em `incremental` está sem cursor ou sem chave primária | Escolha as duas colunas ou mude a tabela para `full_refresh` | | Uma tabela esperada não aparece na lista | É uma view, está num schema de sistema ou o usuário não tem acesso a ela | Confira os grants. Views não são suportadas | | A sincronização falha com `PostgreSQL connection test failed` | O banco ficou inacessível depois da criação do conector | Teste a conexão de novo no Console e confira rede e credenciais | | A tabela no Data Catalog tem só 1.000 linhas | Foi a primeira sincronização, que é uma amostra | Aguarde a próxima execução agendada | ## Próximos passos > **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)** > > Encontre as tabelas copiadas do PostgreSQL na camada raw. > **[Memory](https://docs.strattum.ai/memory/overview.md)** > > Veja como as tabelas limpas viram entidades e relações no grafo. > **Desenvolvimento local** > > 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](https://docs.strattum.ai/data-pipelines/local-development.md). > > | Variável | Onde | Descrição | > | - | - | - | > | `POSTGRES_CLIENT_URL` | Credencial do conector no registro | Connection string do banco de origem | > | `SECRET_BACKEND` | `.env` | Onde as credenciais dos conectores ficam: `json_file`, `aws`, `gcp` ou `azure` | > | `STRATTUM_RESOURCE_CONCURRENCY` | `.env` | Quantas tabelas são lidas ao mesmo tempo. Vazio ou `1` lê uma de cada vez | > > ```bash theme={null} > SECRET_BACKEND=json_file > STRATTUM_RESOURCE_CONCURRENCY= > ``` > > Crie o conector pelo Console local para gravar a credencial no registro antes de disparar o flow. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.