Noções Básicas de PostgreSQL

10 exemplos para você começar com os fundamentos do PostgreSQL - 7 básicos e 3 intermediários.

Pré-requisitos

Instale o PostgreSQL 18 localmente ou use Docker. Você precisa do psql e acesso de superusuário para criar objetos de exemplo.

# Desenvolvimento local com Docker (PostgreSQL 18)
docker run -d --name pg18 -e POSTGRES_PASSWORD=dev -p 5432:5432 postgres:18
psql postgres://postgres:dev@localhost:5432/postgres

Exemplos Básicos

1. Conectar a um Banco de Dados

Cada sessão se conecta a exatamente um banco de dados no cluster.

\c postgres
SELECT current_database(), current_user, version();

• O cluster é a instância PostgreSQL em execução; banco de dados é o alvo da conexão
• \c nome_db no psql muda de banco de dados sem reconectar o cliente binário
• version() retorna a build do servidor; fixe as ferramentas cliente na mesma versão principal quando possível

Relacionado: Arquitetura do Postgres - processos por trás da conexão

2. Criar um Schema e Tabela

Schemas agrupam tabelas, views e funções. public é o schema padrão.

CREATE SCHEMA app AUTHORIZATION postgres;
 
CREATE TABLE app.customers (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email text NOT NULL UNIQUE,
  created_at timestamptz NOT NULL DEFAULT now()
);
 
INSERT INTO app.customers (email) VALUES ('ada@example.com');

• Use schemas para separar aplicativos ou tenants em um único banco de dados
• Prefira colunas de identidade em vez de serial para novas tabelas (PostgreSQL 10+)
• Restrições vivem no catálogo e sobrevivem a reimplementações de aplicativos

3. Consultar com Colunas Explícitas

SQL legível lista colunas e filtra cedo.

SELECT id, email, created_at
FROM app.customers
WHERE email LIKE '%@example.com'
ORDER BY created_at DESC
LIMIT 10;

• Evite SELECT * em código de aplicativo; mudanças de schema quebram clientes silenciosamente
• Filtre em colunas indexadas quando as tabelas crescerem
• LIMIT sem ORDER BY retorna um conjunto de linhas arbitrário

Relacionado: Noções Básicas de Consultas SQL

4. Inspecionar Metadados de Objetos

Catálogos do sistema descrevem cada objeto no cluster.

SELECT n.nspname AS schema, c.relname AS table_name, c.relkind
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'app' AND c.relkind = 'r'
ORDER BY 1, 2;

• pg_class + pg_namespace são o registro de tabelas de baixo nível
• information_schema oferece views padrão SQL com menos detalhes
• Consultas de metadados alimentam migrações, linters e catálogos de dados

Relacionado: Catálogos do Sistema

5. Usar Transações para Escritas em Múltiplas Etapas

Transações ACID agrupam mudanças em uma única unidade atômica.

BEGIN;
INSERT INTO app.customers (email) VALUES ('grace@example.com');
UPDATE app.customers SET email = lower(email) WHERE email = 'grace@example.com';
COMMIT;

• O autocommit padrão envolve cada instrução, a menos que você use BEGIN
• Em caso de erro, ROLLBACK desfaz o trabalho na transação atual
• Mantenha as transações curtas para reduzir a pressão de locks e bloat

Relacionado: Noções Básicas de Transações

6. Adicionar um Índice para Padrões de Busca

Índices B-tree aceleram predicados de igualdade e intervalo em colunas.

CREATE INDEX customers_created_at_idx
  ON app.customers (created_at DESC);
 
EXPLAIN (ANALYZE, BUFFERS)
SELECT id FROM app.customers
WHERE created_at > now() - interval '7 days';

• Índices aceleram leituras, mas adicionam amplificação de escrita em INSERT/UPDATE
• EXPLAIN ANALYZE executa a consulta e mostra os tempos reais
• Indexe apenas o que você consulta; verifique os planos após mudanças de schema

Relacionado: Noções Básicas de Índices

7. Instalar uma Extensão

Extensões fornecem recursos opcionais como módulos controlados.

CREATE EXTENSION IF NOT EXISTS pgcrypto;
 
SELECT gen_random_uuid();

• Extensões são versionadas e registradas em pg_extension
• Algumas extensões requerem superusuário ou CREATE no banco de dados
• Fixe as versões das extensões em scripts de migração para reprodutibilidade

Exemplos Intermediários

8. Definir search_path com Segurança

Nomes não qualificados são resolvidos via search_path. Configuração incorreta causa bugs de tabela errada.

SHOW search_path;
 
SET search_path = app, public;
 
SELECT email FROM customers LIMIT 1;
 
-- Mais seguro em aplicativos: sempre qualifique o schema
SELECT email FROM app.customers LIMIT 1;

• O padrão é "$user", public - schemas vazios podem surpreender novas roles
• Código sensível à segurança deve qualificar o schema ou definir o path por sessão
• Nunca confie em public para dados multi-tenant sem RLS

Relacionado: Banco de Dados, Schema e Search Path

9. Verificar Sinais de Saúde do Servidor

Consultas rápidas ao catálogo expõem conexões, dicas de bloat e versão.

SELECT count(*) AS backends FROM pg_stat_activity;
 
SELECT datname, numbackends, xact_commit, blks_read
FROM pg_stat_database
WHERE datname = current_database();

• pg_stat_activity lista sessões ativas e eventos de espera
• pg_stat_database agrega commits, leituras e conflitos por banco de dados
• Combine verificações de catálogo com métricas do SO (CPU, disco, memória) para triagem

Relacionado: Arquitetura do Postgres

10. Escolher timestamptz para Eventos

Armazene instantes em UTC; converta na borda do aplicativo.

ALTER TABLE app.customers
  ADD COLUMN last_login_at timestamptz;
 
UPDATE app.customers
SET last_login_at = now()
WHERE email = 'ada@example.com';
 
SELECT email, last_login_at AT TIME ZONE 'America/New_York' AS login_ny
FROM app.customers;

• timestamptz armazena UTC internamente; a exibição depende do TimeZone da sessão
• Evite timestamp without time zone para tempos de eventos do mundo real
• Documente as suposições de fuso horário nos contratos da API

Relacionado: Data, Hora e Timestamptz

Versões da Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.