Noções Básicas de psql

7 exemplos para uso diário do psql - 5 básicos e 2 intermediários.

Pré-requisitos

psql --version   # combine a versão principal com a do servidor, quando possível

• Instale postgresql-client-18 (ou a versão principal de destino) nas estações de trabalho de administração.
• Armazene os padrões de conexão em ~/.pgpass ou em um gerenciador de segredos - não no histórico do shell.

Exemplos Básicos

1. Conectar a um Banco de Dados

psql "postgresql://app_ro:****@db.internal:5432/myapp?sslmode=require"
# ou
psql -h db.internal -p 5432 -U app_ro -d myapp

• sslmode=require impõe TLS na comunicação.
• Um nome de banco de dados incorreto ainda se conecta - você pode consultar silenciosamente o esquema errado.
• Use funções somente leitura para consultas exploratórias em produção.

2. Mudar de Banco de Dados (\c)

\c myapp
\c myapp app_ro
\conninfo

• \c dbname [username] abre uma nova conexão na mesma sessão do psql.
• \conninfo exibe o host, porta e usuário - verifique antes de executar operações destrutivas.
• Reconectar redefine GUCs de sessão como search_path, a menos que sejam definidos por função.

Relacionado: Scripting com psql - execuções não interativas

3. Listar Objetos (\dt, \d)

\dt public.*
\d+ orders
\dn
\df public.*

• \d+ adiciona o tamanho do armazenamento e comentários de descrição.
• \dn lista os esquemas - crítico em layouts multi-tenant.
• Os meta-comandos consultam catálogos - eles respeitam seu search_path atual.

4. Cronometrar Consultas (\timing)

\timing on
SELECT count(*) FROM orders WHERE created_at > now() - interval '7 days';

• Mostra o tempo de execução do servidor, não o tempo de ida e volta da rede.
• Ative para toda investigação de desempenho ad-hoc.
• Combine com EXPLAIN (ANALYZE, BUFFERS) para detalhes no nível do plano.

Relacionado: Regras de Índice e Consulta - EXPLAIN antes de mesclar

5. Hábitos Seguros de LIMIT

-- Sempre limite as SELECTs exploratórias em tabelas grandes
SELECT id, status, created_at
FROM orders
ORDER BY created_at DESC
LIMIT 50;
 
-- Evite varreduras completas acidentais
SELECT * FROM events LIMIT 100;  -- ainda lê se não houver um plano amigável para índice

• LIMIT sem ORDER BY retorna uma fatia arbitrária.
• SELECT * em linhas JSONB amplas transfere megabytes por linha.
• Use réplicas de leitura para exploração analítica quando disponíveis.

Exemplos Intermediários

6. Formatos de Saída

\x on
SELECT * FROM pg_stat_activity WHERE pid = pg_backend_pid();
 
\a
\t
SELECT setting FROM pg_settings WHERE name = 'max_connections';

• A exibição expandida (\x) ajuda em consultas de catálogo amplas.
• \a (alinhado desativado) + \t (apenas tuplas) = TSV amigável para scripts.
• \pset footer off remove contagens de linhas para análise por máquina.

7. Barreiras de Proteção de Sessão Somente Leitura

BEGIN READ ONLY;
SELECT sum(amount) FROM payments WHERE paid_at >= current_date;
ROLLBACK;

# Conecte-se explicitamente como uma função somente leitura
psql -U app_ro -d myapp -c "SELECT 1"

• BEGIN READ ONLY bloqueia UPDATE acidental na mesma transação.
• Prefira uma função sem INSERT/UPDATE/DELETE em produção.
• Algumas equipes criam um alias psql_prod='psql -U app_ro ...' apenas em caixas de salto aprovadas.

Versões da Pilha: 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+.