pulse-libs/libs/database/POSTGRESQL.md

PostgreSQL — Patterns e Anti-patterns

Conexão | Schemas | JSONB | Junções | Window Functions | Migrações | EXPLAIN

Comandos Rápidos

psql "postgresql://user:pass@host:5432/db?sslmode=require"
psql -h localhost -U user -d db -c "SELECT NOW();"
psql -h host -U user -d db -f migration.sql

Schema Design

-- UUIDs para PK distribuído-friendly (ativar extensão primeiro)
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL UNIQUE,
    name TEXT NOT NULL,
    role TEXT NOT NULL DEFAULT 'user' CHECK(role IN ('user','admin','moderator')),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Auto-update updated_at
CREATE OR REPLACE FUNCTION update_modified_column()
RETURNS TRIGGER AS $$ BEGIN NEW.updated_at = NOW(); RETURN NEW; END; $$ LANGUAGE plpgsql;

CREATE TRIGGER update_users_modtime BEFORE UPDATE ON users
FOR EACH ROW EXECUTE FUNCTION update_modified_column();

-- Enum
CREATE TYPE order_status AS ENUM ('pending','paid','shipped','cancelled');

JSONB Ops

INSERT INTO orders (metadata) VALUES ('{"source":"web","items":[{"sku":"A1","qty":2}]}'::jsonb);

SELECT * FROM orders WHERE metadata->>'source' = 'web';
SELECT * FROM orders WHERE metadata->'items' @> '[{"sku":"A1"}]'::jsonb; -- @> contains
UPDATE orders SET metadata = jsonb_set(metadata, '{source}', '"mobile"') WHERE id = '...';
SELECT metadata->>'coupon' AS coupon, COUNT(*) FROM orders GROUP BY 1;

Indexes

CREATE UNIQUE INDEX idx_users_email ON users(email);            -- único
CREATE INDEX idx_orders_user_created ON orders(user_id, created_at); -- composto
CREATE INDEX idx_orders_active ON orders(user_id, created_at)  -- parcial
  WHERE status NOT IN ('delivered','cancelled');
CREATE INDEX idx_orders_metadata ON orders USING GIN(metadata);  -- GIN para JSONB

Window Functions

SELECT date, revenue,
  SUM(revenue) OVER (ORDER BY date)       AS cumulative_revenue,  -- running total
  AVG(revenue) OVER (PARTITION BY region) AS avg_by_region,
  RANK() OVER (ORDER BY revenue DESC)      AS ranking
FROM daily_sales;

JOINS Rápidos

-- LEFT JOIN pega todos os usuários, mesmo sem pedidos
SELECT u.name, COUNT(o.id) AS order_count, COALESCE(SUM(o.total), 0) AS total_spent
FROM users u LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.id, u.name HAVING COUNT(o.id) > 5 ORDER BY total_spent DESC;

CTEs (WITH)

WITH active_users AS (
  SELECT id, name FROM users WHERE active = true
)
SELECT au.name, COUNT(o.id) AS orders
FROM active_users au LEFT JOIN orders o ON o.user_id = au.id
GROUP BY au.name;

EXPLAIN ANALYZE (antes de otimizar)

EXPLAIN ANALYZE SELECT ... -- SEMPRE antes de criar um índice

Migrations — Padrão

# Criar timestamped
psql -h host -U user -d db -f migrations/2025-06-19_add_field.sql

Checklist de Otimização

• EXPLAIN ANALYZE antes e depois de cada mudança
• Medir tempo de resposta alvo antes de otimizar
• Evitar SELECT * em produção
• Criar índices para colunas em WHERE, JOIN, ORDER BY
• Índice parcial para subconjuntos pequenos
• Partial/Paginado para tabelas grandes