> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PostgreSQL

> Configure o conector PostgreSQL para ingerir tabelas de bancos relacionais na plataforma strattum.ai.

<Note>
  Este guia cobre a configuração do conector PostgreSQL para **desenvolvimento local**. Para ativar o conector via Console strattum.ai, consulte o [Quickstart de Data Pipelines](/data-pipelines/quickstart).
</Note>

## Visão geral

O conector PostgreSQL ingere tabelas de bancos relacionais PostgreSQL na infraestrutura strattum.ai. Você pode configurar tabelas individuais ou sincronizar schemas completos, com suporte a dois modos de carga:

| Modo             | Descrição                                                                          |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Incremental**  | Carrega apenas linhas novas ou modificadas usando o campo `updated_at` como cursor |
| **Full Refresh** | Recarrega a tabela completa a cada ciclo de sincronização                          |

***

## Pré-requisitos

<CardGroup cols={2}>
  <Card title="PostgreSQL 12 ou superior" icon="database">
    O conector é compatível com PostgreSQL 12+, seja em cloud (RDS, Cloud SQL, Supabase) ou on-premise.
  </Card>

  <Card title="Usuário com permissão de leitura" icon="user-shield">
    Recomendamos criar um usuário dedicado com permissão apenas de `SELECT`. Veja o passo a passo abaixo.
  </Card>
</CardGroup>

***

## Variáveis de ambiente

Adicione a variável abaixo ao arquivo `.env` (veja o guia de [configuração local](/data-pipelines/local-development#2-configurar-variáveis-de-ambiente)):

| Variável              | Descrição                                     | Exemplo                                   |
| --------------------- | --------------------------------------------- | ----------------------------------------- |
| `POSTGRES_CLIENT_URL` | Connection string completa do banco de origem | `postgresql://user:pass@host:5432/dbname` |

```bash theme={null}
POSTGRES_CLIENT_URL=postgresql://strattum_reader:senha_segura@seu-host.rds.amazonaws.com:5432/nome_do_banco
```

<Warning>
  Nunca comite o arquivo `.env` no repositório. Certifique-se que ele está listado no `.gitignore`.
</Warning>

***

## Como criar um usuário read-only

Recomendamos usar um usuário dedicado com acesso apenas de leitura para minimizar a superfície de risco. Execute os comandos abaixo conectado ao banco com um usuário administrador:

<Steps>
  <Step title="Crie o usuário">
    ```sql theme={null}
    CREATE USER strattum_reader WITH PASSWORD 'senha_segura';
    ```

    <Tip>
      Use uma senha forte e aleatória. Ferramentas como `openssl rand -base64 32` geram senhas seguras diretamente no terminal.
    </Tip>
  </Step>

  <Step title="Conceda acesso ao banco">
    ```sql theme={null}
    GRANT CONNECT ON DATABASE nome_do_banco TO strattum_reader;
    ```
  </Step>

  <Step title="Conceda acesso ao schema">
    ```sql theme={null}
    GRANT USAGE ON SCHEMA public TO strattum_reader;
    ```

    Repita para outros schemas que deseja expor além do `public`.
  </Step>

  <Step title="Conceda permissão de leitura nas tabelas existentes">
    ```sql theme={null}
    GRANT SELECT ON ALL TABLES IN SCHEMA public TO strattum_reader;
    ```
  </Step>

  <Step title="Garanta acesso a tabelas futuras">
    ```sql theme={null}
    ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO strattum_reader;
    ```

    Este comando garante que novas tabelas criadas no schema também sejam acessíveis ao usuário.
  </Step>
</Steps>

***

## Acesso de rede

O worker strattum.ai precisa conseguir alcançar o banco PostgreSQL na porta configurada (padrão `5432`).

<CardGroup cols={2}>
  <Card title="Cloud (RDS, Cloud SQL)" icon="cloud">
    Adicione o IP do ambiente strattum.ai ou o CIDR da VPC ao Security Group / firewall do banco.
  </Card>

  <Card title="On-premise" icon="server">
    Verifique se o banco aceita conexões externas no `pg_hba.conf` e se o firewall da rede permite o tráfego de entrada na porta `5432`.
  </Card>
</CardGroup>

<Note>
  Para ambientes com requisitos de rede mais restritos, consulte o time strattum.ai para configurar uma conexão via túnel ou VPN privada.
</Note>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Guia de desenvolvimento local" icon="terminal" href="/data-pipelines/local-development">
    Configure o ambiente local completo com Prefect, worker e Docker Compose.
  </Card>

  <Card title="Quickstart — Data Pipelines" icon="rocket" href="/data-pipelines/quickstart">
    Ative conectores via Console strattum.ai sem precisar de ambiente local.
  </Card>
</CardGroup>