PostgreSQL - Banco de Dados Relacional

Visão Geral

PostgreSQL é um sistema de gerenciamento de banco de dados relacional open-source poderoso, com mais de 35 anos de desenvolvimento ativo. O Lumina Flow Builder oferece integração completa com PostgreSQL através de 5 operações principais.

Operações Disponíveis

1. Execute Query - Consultas SQL Personalizadas

Executa qualquer consulta SQL (SELECT, CREATE, ALTER, etc.) com total flexibilidade.

Quando usar: - SELECT com JOINs complexos - Agregações e relatórios - CTEs e subconsultas - DDL (CREATE TABLE, ALTER, etc.) - Queries personalizadas

Exemplo rápido:

{
  "operation": "executeQuery",
  "query": "SELECT * FROM clientes WHERE cidade = '{{cidade}}' LIMIT 10",
  "responseVariable": "clientes"
}

2. Insert - Inserir Registro

Insere novo registro na tabela de forma segura com prepared statements.

Quando usar: - Cadastro de novos clientes - Criar novo pedido - Registrar log de evento - Adicionar produto

Exemplo rápido:

{
  "operation": "insert",
  "table": "clientes",
  "values": {
    "nome": "{{nome}}",
    "email": "{{email}}",
    "data_cadastro": "CURRENT_TIMESTAMP"
  }
}

3. Update - Atualizar Registro

Atualiza registros existentes baseado em condições WHERE.

Quando usar: - Atualizar perfil de cliente - Mudar status de pedido - Corrigir dados incorretos - Atualização condicional

Exemplo rápido:

{
  "operation": "update",
  "table": "pedidos",
  "values": {
    "status": "enviado",
    "data_envio": "CURRENT_TIMESTAMP"
  },
  "conditions": {
    "id": "{{pedidoId}}"
  }
}

4. Delete - Deletar Registro

Remove registros da tabela baseado em condições WHERE.

Quando usar: - Cancelar pedido - Excluir conta de usuário - Limpar dados temporários - Remover item específico

IMPORTANTE: SEMPRE use com conditions! Nunca delete sem WHERE.

Exemplo rápido:

{
  "operation": "delete",
  "table": "sessoes",
  "conditions": {
    "expires_at": "< CURRENT_TIMESTAMP"
  }
}

5. InsertOrUpdate (Upsert) - Inserir ou Atualizar

Insere registro se não existe, atualiza se já existe (ON CONFLICT).

Quando usar: - Sincronização de dados externos - Operações idempotentes - Criar ou atualizar perfil - Import de dados

Exemplo rápido:

{
  "operation": "insertOrUpdate",
  "table": "produtos",
  "values": {
    "sku": "{{sku}}",
    "nome": "{{nome}}",
    "preco": "{{preco}}"
  },
  "conflictKeys": ["sku"]
}

Configuração de Conexão

Todas as operações requerem objeto config com credenciais:

{
  "host": "localhost",
  "port": 5432,
  "database": "nome_database",
  "user": "usuario",
  "password": "senha",
  "ssl": false
}

Segurança: NUNCA exponha credenciais em código! Use variáveis de ambiente.

Características do PostgreSQL

Vantagens

ACID completo: Transações confiáveis
SQL avançado: CTEs, window functions, arrays, JSON
Extensível: Tipos personalizados, funções, operadores
Full-text search: Busca textual nativa
JSON/JSONB: Suporte NoSQL híbrido
Replicação: Múltiplas opções de replicação
Open-source: Grátis e código aberto
Performance: Excelente para leitura e escrita

Recursos Avançados

CTEs Recursivas: Queries hierárquicas
Window Functions: Análises complexas
JSONB: Documentos com índices
Arrays: Colunas com múltiplos valores
Stored Procedures: Lógica no banco
Triggers: Automação de eventos
Particionamento: Dividir tabelas grandes
Foreign Data Wrappers: Acesso a outros bancos

Tipos de Dados Comuns

Tipo	Descrição	Exemplo
INTEGER	Número inteiro	42
BIGINT	Inteiro grande	9223372036854775807
NUMERIC(p,s)	Decimal preciso	123.45
VARCHAR(n)	Texto variável	'João Silva'
TEXT	Texto ilimitado	'Descrição longa...'
BOOLEAN	Verdadeiro/Falso	true, false
DATE	Data	'2025-01-15'
TIMESTAMP	Data e hora	'2025-01-15 14:30:00'
TIMESTAMPTZ	Com timezone	'2025-01-15 14:30:00-03'
JSON/JSONB	Objeto JSON	'{"nome": "João"}'
ARRAY	Array de valores	ARRAY[1,2,3]
UUID	Identificador único	'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11'

Boas Práticas Gerais

✅ Segurança

Use prepared statements (implementado automaticamente)
NUNCA concatene variáveis no SQL
Use SSL em produção
Crie usuário com permissões mínimas necessárias
Rotacione senhas regularmente

✅ Performance

Crie índices em colunas de WHERE e JOIN
Use LIMIT em queries de consulta
Execute EXPLAIN ANALYZE para otimizar
Use connection pooling
Normalize dados adequadamente (3FN)
Particione tabelas muito grandes

✅ Manutenção

Execute VACUUM e ANALYZE regularmente
Monitore tamanho de índices
Configure backups automáticos
Use transações para operações relacionadas
Documente estrutura do banco

❌ Evite

Não use SELECT * em produção
Não faça queries dentro de loops
Não ignore índices
Não exponha credenciais
Não delete/update sem WHERE
Não use DISTINCT quando GROUP BY resolve

Exemplo Completo: Sistema de Pedidos

{
  "name": "PostgreSQL - Sistema Pedidos Completo",
  "nodes": [
    {
      "id": "start_1",
      "type": "start",
      "data": { "label": "Início" }
    },
    {
      "id": "buscar_cliente",
      "type": "postgresql",
      "data": {
        "operation": "executeQuery",
        "query": "SELECT id, nome FROM clientes WHERE telefone = '{{phone}}'",
        "responseVariable": "cliente"
      }
    },
    {
      "id": "inserir_pedido",
      "type": "postgresql",
      "data": {
        "operation": "insert",
        "table": "pedidos",
        "values": {
          "cliente_id": "{{cliente.rows[0].id}}",
          "total": "{{total}}",
          "status": "pendente"
        },
        "responseVariable": "pedido"
      }
    },
    {
      "id": "atualizar_status",
      "type": "postgresql",
      "data": {
        "operation": "update",
        "table": "pedidos",
        "values": { "status": "pago" },
        "conditions": { "id": "{{pedido.insertedRow.id}}" }
      }
    },
    {
      "id": "end_1",
      "type": "end",
      "data": { "label": "Fim" }
    }
  ]
}

Automações Possíveis

1. CRM Automático

Inserir leads automaticamente
Atualizar status de oportunidades
Registrar interações
Gerar relatórios de vendas

2. E-commerce

Sincronizar produtos de API
Gerenciar inventário
Processar pedidos
Atualizar preços dinamicamente

3. Sistema de Tickets

Criar tickets de suporte
Atualizar status
Atribuir responsáveis
Gerar métricas SLA

4. Auditoria e Logs

Registrar ações de usuários
Monitorar acessos
Gerar relatórios de compliance
Limpar logs antigos

Recursos de Aprendizado

Documentação Oficial

Ferramentas Úteis

pgAdmin: Interface gráfica
DBeaver: Cliente universal
psql: CLI oficial
pg_dump: Backup e restore

Troubleshooting

Erro: "Connection refused"

Verifique se PostgreSQL está rodando
Confirme host e porta corretos
Verifique firewall

Erro: "Authentication failed"

Confirme usuário e senha
Verifique pg_hba.conf
Teste conexão com psql

Erro: "Relation does not exist"

Tabela não existe ou nome incorreto
Verifique schema (public por padrão)
Case-sensitive se usar aspas

Erro: "Duplicate key value violates unique constraint"

Tentando inserir valor duplicado em campo UNIQUE/PK
Use UPSERT (insertOrUpdate) se apropriado
Verifique se registro já existe

Suporte

Para questões sobre PostgreSQL no Lumina Flow Builder:

Verifique documentação específica de cada operação
Teste query no psql antes de usar no flow
Use EXPLAIN ANALYZE para problemas de performance
Consulte logs do PostgreSQL para erros detalhados

Próximos Passos

→ MySQL - Alternativa popular open-source → Microsoft SQL Server - Solução enterprise da Microsoft → MongoDB - Banco NoSQL para dados não-estruturados