psql — Terminal Interativo do PostgreSQL

psql é o terminal interativo do PostgreSQL, repleto de recursos. Ele permite que você escreva e execute consultas, inspecione objetos do banco de dados, importe/exporte dados, crie scripts para operações em lote e personalize a formatação da saída — tudo a partir da linha de comando.

Pré-requisitos

Antes de usar o psql, verifique se ele está instalado e disponível:

# Check if psql is installed
psql --version

# If not found, install PostgreSQL client tools:

# macOS (Homebrew)
brew install libpq
brew link --force libpq

# Ubuntu / Debian
sudo apt install postgresql-client

# CentOS / RHEL
sudo yum install postgresql

# Alpine
apk add postgresql-client

# Windows — install PostgreSQL via the official installer or use WSL

O psql é distribuído como parte do pacote postgresql-client. O servidor (postgresql) não é necessário — você só precisa do cliente para se conectar a uma instância remota do PostgreSQL.

Referência Rápida

Conectando

# 1. CLI flags
psql -h host -p port -U user -d dbname

# 2. Connection URI
# WARNING: Password in URI is visible in shell history and process listings.
#          Prefer ~/.pgpass for production use (see method 4 below).
psql "postgresql://user:YOUR_PASSWORD@host:port/dbname"

# 3. Environment variables (no flags needed)
export PGHOST=localhost
export PGPORT=5432
export PGDATABASE=mydb
export PGUSER=postgres
# WARNING: PGPASSWORD is visible in process listings (e.g. `ps aux`).
#          Use ~/.pgpass in production instead.
export PGPASSWORD=YOUR_PASSWORD
psql                       # picks up all params from env

# 4. ~/.pgpass file (RECOMMENDED for passwords)
#    Format: hostname:port:database:username:password
touch ~/.pgpass && chmod 600 ~/.pgpass
# Then manually edit ~/.pgpass and add entries (avoids password in shell history):
# hostname:port:database:username:password
# Example: localhost:5432:mydb:postgres:YOUR_PASSWORD
psql -h localhost -U postgres -d mydb   # no password prompt

# 5. Execute and exit
psql -f script.sql dbname                        # execute file then exit
psql -c "SELECT 1" dbname                        # run single command then exit
psql -1 -f migration.sql dbname                  # run in single transaction

# 6. Service connection (reads from pg_service.conf)
psql service=mydb_prod

# 7. Reconnect within a session
\c dbname                                       # reconnect to different db
\c -reuse-previous=on sslmode=require           # change only sslmode
\c "host=newhost port=5432 dbname=mydb"         # conninfo string

Em caso de falha na conexão: o modo interativo mantém a conexão anterior; o modo de script a fecha e todos os comandos de banco de dados subsequentes falharão até a próxima \c bem-sucedida.

Chaves importantes: -h host, -p porta, -U usuário, -d banco de dados, -w sem solicitação de senha, -W forçar solicitação de senha, -1 transação única, -f executar arquivo, -c executar comando, -t apenas tuplas, -x expandido, -A desalinhado, -E eco de consultas ocultas (\d internas), -L arquivo de log, -X pular ~/.psqlrc.

Precedência de conexão: Chaves da CLI > variáveis de ambiente > pg_service.conf > padrões. Precedência de senha: string de conexão/chave de senha > PGPASSWORD env > ~/.pgpass. Use ~/.pgpass em vez de PGPASSWORD em produção — PGPASSWORD é visível nas listagens de processos (ps aux).

Inspeção de Objetos (família \d)

…