Comandos do psql
Os metacomandos rodam dentro do psql (o cliente de terminal do PostgreSQL), não no servidor. Começam com uma barra invertida e não precisam de ponto e vírgula.
| O que faz | Comando |
|---|
| Listar bancos de dados | \l |
| Conectar a outro banco de dados | \c shop |
| Listar tabelas | \dt |
| Listar tabelas de todos os schemas | \dt *.* |
| Descrever uma tabela (colunas, índices, chaves) | \d users |
| Descrever com armazenamento e comentários | \d+ users |
| Listar schemas | \dn |
| Listar views | \dv |
| Listar índices | \di |
| Listar funções | \df |
| Listar papéis (usuários) | \du |
| Mostrar a conexão atual | \conninfo |
| Executar SQL de um arquivo | \i setup.sql |
| Ligar ou desligar o tempo das consultas | \timing |
| Saída expandida (uma coluna por linha) | \x |
| Editar a última consulta no seu editor | \e |
| Ajuda sobre a sintaxe SQL | \h CREATE TABLE |
| Listar todos os metacomandos | \? |
| Sair do psql | \q |
Conectar pelo terminal
| O que faz | Comando |
|---|
| Conectar como um usuário a um banco de dados | psql -U postgres -d shop |
| Conectar a um host e porta remotos | psql -h db.example.com -p 5432 -U app -d shop |
| Conectar com uma URL de conexão | psql postgresql://app:secret@localhost:5432/shop |
| Executar uma consulta e sair | psql -d shop -c "SELECT count(*) FROM users;" |
| Executar um arquivo SQL | psql -d shop -f setup.sql |
| Criar um banco de dados pelo shell | createdb shop |
| Excluir um banco de dados pelo shell | dropdb shop |
Bancos de dados e schemas
| O que faz | SQL |
|---|
| Criar um banco de dados | CREATE DATABASE shop; |
| Excluir um banco de dados | DROP DATABASE shop; |
| Mostrar o banco de dados atual | SELECT current_database(); |
| Criar um schema | CREATE SCHEMA sales; |
| Mostrar a ordem de busca dos schemas | SHOW search_path; |
| Procurar primeiro em um schema | SET search_path TO sales, public; |
| Mostrar a versão do servidor | SELECT version(); |
Tabelas e tipos de dados
| O que faz | SQL |
|---|
| Criar uma tabela com chave de identidade | CREATE TABLE products (id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY, name text NOT NULL, price numeric(10,2) CHECK (price >= 0), created_at timestamptz DEFAULT now()); |
| Adicionar uma coluna | ALTER TABLE users ADD COLUMN phone text; |
| Renomear uma coluna | ALTER TABLE users RENAME COLUMN country TO country_code; |
| Mudar o tipo de uma coluna | ALTER TABLE users ALTER COLUMN age TYPE smallint; |
| Definir um valor padrão | ALTER TABLE users ALTER COLUMN active SET DEFAULT false; |
| Excluir uma coluna | ALTER TABLE users DROP COLUMN tags; |
| Esvaziar uma tabela e reiniciar a identidade | TRUNCATE orders, users RESTART IDENTITY; |
| Excluir uma tabela se existir | DROP TABLE IF EXISTS products; |
| Decimal exato para dinheiro | numeric(10,2) |
| Data e hora com fuso horário | timestamptz |
| UUID aleatório | SELECT gen_random_uuid(); |
| Tipo enum | CREATE TYPE mood AS ENUM ('happy', 'sad'); |
Restrições e chaves
| O que faz | SQL |
|---|
| Adicionar uma chave primária | ALTER TABLE logs ADD PRIMARY KEY (id); |
| Chave estrangeira que exclui as linhas filhas | CREATE TABLE reviews (id integer PRIMARY KEY, user_id integer REFERENCES users(id) ON DELETE CASCADE); |
| Adicionar uma restrição CHECK | ALTER TABLE orders ADD CONSTRAINT amount_positive CHECK (amount > 0); |
| Único com NULLs contados como iguais (15+) | CREATE TABLE emails (address text UNIQUE NULLS NOT DISTINCT); |
| Tornar uma coluna obrigatória | ALTER TABLE users ALTER COLUMN country SET NOT NULL; |
| Excluir uma restrição | ALTER TABLE users DROP CONSTRAINT users_email_key; |
SELECT, WHERE e JOIN padrão estão na folha de consulta SQL; estas são as formas do PostgreSQL.
| O que faz | SQL |
|---|
| Busca sem diferenciar maiúsculas | SELECT * FROM users WHERE name ILIKE 'a%'; |
| Busca com expressão regular | SELECT * FROM users WHERE email ~ '@example\.com$'; |
| Primeira linha de cada grupo | SELECT DISTINCT ON (user_id) user_id, amount FROM orders ORDER BY user_id, amount DESC; |
| Limite e deslocamento | SELECT * FROM users ORDER BY id LIMIT 10 OFFSET 20; |
| Limite de linhas padrão | SELECT * FROM users ORDER BY id FETCH FIRST 5 ROWS ONLY; |
| Conversão com :: | SELECT '42'::integer + 1; |
| Valor alternativo para NULL | SELECT name, COALESCE(email, 'none') FROM users; |
| Comparar tratando NULLs como iguais | SELECT * FROM users WHERE email IS DISTINCT FROM 'asha@example.com'; |
| Gerar uma série de números | SELECT * FROM generate_series(1, 5); |
| Agregar em uma string | SELECT string_agg(name, ', ' ORDER BY name) FROM users; |
| Agregação condicional | SELECT count(*) FILTER (WHERE status = 'paid') AS paid, count(*) AS total FROM orders; |
Inserir, atualizar, excluir e upsert
| O que faz | SQL |
|---|
| Inserir e receber o novo id | INSERT INTO users (name, email) VALUES ('Dana', 'dana@example.com') RETURNING id; |
| Inserir várias linhas | INSERT INTO users (name) VALUES ('Eli'), ('Femi'); |
| Upsert (inserir ou atualizar) | INSERT INTO users (name, email) VALUES ('Asha K', 'asha@example.com') ON CONFLICT (email) DO UPDATE SET name = EXCLUDED.name; |
| Inserir ignorando duplicados | INSERT INTO users (name, email) VALUES ('Ben', 'ben@example.com') ON CONFLICT DO NOTHING; |
| Atualizar e ver as linhas alteradas | UPDATE employees SET salary = salary * 1.1 WHERE department = 'IT' RETURNING name, salary; |
| Atualizar a partir de outra tabela | UPDATE orders SET status = 'vip' FROM users WHERE orders.user_id = users.id AND users.country = 'IN'; |
| Excluir e ver o que foi excluído | DELETE FROM orders WHERE status = 'refunded' RETURNING id; |
| Excluir usando outra tabela | DELETE FROM orders USING users WHERE orders.user_id = users.id AND users.active = false; |
| Copiar linhas para uma nova tabela | CREATE TABLE paid_orders AS SELECT * FROM orders WHERE status = 'paid'; |
JSONB
| O que faz | SQL |
|---|
| Obter um campo como JSON | SELECT profile -> 'plan' FROM users; |
| Obter um campo como texto | SELECT profile ->> 'plan' FROM users; |
| Obter um campo aninhado como texto | SELECT profile #>> '{address,city}' FROM users; |
| Linhas cujo JSON contém um valor | SELECT * FROM users WHERE profile @> '{"plan": "pro"}'; |
| Linhas que têm uma chave | SELECT * FROM users WHERE profile ? 'city'; |
| Definir uma chave | UPDATE users SET profile = jsonb_set(profile, '{plan}', '"team"') WHERE id = 2; |
| Mesclar objetos | UPDATE users SET profile = profile || '{"beta": true}'; |
| Remover uma chave | UPDATE users SET profile = profile - 'city'; |
| Montar JSON a partir de colunas | SELECT jsonb_build_object('id', id, 'name', name) FROM users; |
| Linhas como um array JSON | SELECT jsonb_agg(users) FROM users; |
| Índice para buscas com @> e ? | CREATE INDEX users_profile_idx ON users USING gin (profile); |
Arrays
| O que faz | SQL |
|---|
| Literal de array | SELECT ARRAY[1, 2, 3]; |
| Linhas em que o array tem um valor | SELECT * FROM users WHERE 'sql' = ANY(tags); |
| Linhas em que o array contém todos estes | SELECT * FROM users WHERE tags @> ARRAY['sql', 'python']; |
| Uma linha por elemento | SELECT name, unnest(tags) FROM users; |
| Adicionar um elemento no fim | UPDATE users SET tags = array_append(tags, 'sql') WHERE id = 2; |
| Tamanho do array | SELECT name, cardinality(tags) FROM users; |
Datas e horas
| O que faz | SQL |
|---|
| Agora, com fuso horário | SELECT now(); |
| Hoje | SELECT current_date; |
| Somar um intervalo | SELECT current_date + INTERVAL '7 days'; |
| Linhas dos últimos 30 dias | SELECT * FROM orders WHERE created_at > now() - INTERVAL '30 days'; |
| Truncar para o mês | SELECT date_trunc('month', created_at) AS month, sum(amount) FROM orders GROUP BY 1 ORDER BY 1; |
| Extrair uma parte | SELECT EXTRACT(YEAR FROM hired_on) FROM employees; |
| Diferença entre datas (dias) | SELECT DATE '2026-12-25' - DATE '2026-11-17'; |
| Idade entre datas | SELECT name, age(current_date, hired_on) FROM employees; |
| Formatar uma data como texto | SELECT to_char(hired_on, 'DD Mon YYYY') FROM employees; |
| Converter texto em data | SELECT to_date('17/11/2026', 'DD/MM/YYYY'); |
| Converter para um fuso horário | SELECT now() AT TIME ZONE 'Asia/Kolkata'; |
Funções de texto
| O que faz | SQL |
|---|
| Concatenar (NULL resulta em NULL) | SELECT name || ' <' || email || '>' FROM users; |
| Concatenar ignorando NULLs | SELECT concat_ws(' ', name, email) FROM users; |
| Maiúsculas e minúsculas | SELECT upper(name), lower(name) FROM users; |
| Comprimento | SELECT name, length(name) FROM users; |
| Parte de uma string | SELECT substring(name FROM 1 FOR 2) FROM users; |
| Substituir | SELECT replace(email, '@example.com', '') FROM users; |
| Dividir e pegar uma parte | SELECT split_part(email, '@', 2) FROM users; |
| Substituição com expressão regular | SELECT regexp_replace('a1b22c', '[0-9]+', '', 'g'); |
| Remover espaços | SELECT trim(' hi '); |
CTEs e funções de janela
| O que faz | SQL |
|---|
| Nomear uma subconsulta com WITH | WITH paid AS (SELECT user_id, sum(amount) AS total FROM orders WHERE status = 'paid' GROUP BY user_id) SELECT * FROM paid WHERE total > 50; |
| CTE recursiva (contar até 5) | WITH RECURSIVE n(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM n WHERE i < 5) SELECT i FROM n; |
| Numerar linhas por grupo | SELECT name, department, ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) FROM employees; |
| Classificar com empates | SELECT name, DENSE_RANK() OVER (ORDER BY salary DESC) FROM employees; |
| Total acumulado | SELECT id, amount, sum(amount) OVER (ORDER BY id) FROM orders; |
| Valor da linha anterior | SELECT name, salary, LAG(salary) OVER (ORDER BY hired_on) FROM employees; |
| Juntar cada linha à sua própria subconsulta | SELECT u.name, o.amount FROM users u CROSS JOIN LATERAL (SELECT amount FROM orders WHERE user_id = u.id ORDER BY amount DESC LIMIT 1) o; |
Índices
| O que faz | SQL |
|---|
| Índice B-tree (o padrão) | CREATE INDEX orders_user_idx ON orders (user_id); |
| Índice único | CREATE UNIQUE INDEX employees_name_idx ON employees (name); |
| Índice de várias colunas | CREATE INDEX orders_user_created_idx ON orders (user_id, created_at); |
| Índice parcial | CREATE INDEX orders_paid_idx ON orders (created_at) WHERE status = 'paid'; |
| Índice de expressão | CREATE INDEX users_lower_email_idx ON users (lower(email)); |
| Índice de cobertura (index-only scans) | CREATE INDEX orders_user_cover_idx ON orders (user_id) INCLUDE (amount); |
| Criar sem bloquear escritas | CREATE INDEX CONCURRENTLY orders_status_idx ON orders (status); |
| Excluir um índice | DROP INDEX IF EXISTS orders_user_idx; |
| Ver o plano | EXPLAIN SELECT * FROM orders WHERE user_id = 1; |
| Ver o plano com tempos reais | EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 1; |
Transações e locks
| O que faz | SQL |
|---|
| Iniciar, depois manter ou desfazer | BEGIN; UPDATE employees SET salary = 0 WHERE id = 3; ROLLBACK; |
| Desfazer parte de uma transação | BEGIN; INSERT INTO users (name) VALUES ('Gil'); SAVEPOINT s1; DELETE FROM users WHERE name = 'Gil'; ROLLBACK TO s1; COMMIT; |
| Isolamento mais rigoroso | BEGIN ISOLATION LEVEL SERIALIZABLE; SELECT count(*) FROM orders; COMMIT; |
| Bloquear as linhas que você lê | BEGIN; SELECT * FROM orders WHERE id = 1 FOR UPDATE; COMMIT; |
| Fila de tarefas: pular linhas bloqueadas | BEGIN; SELECT id FROM orders WHERE status = 'paid' ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED; COMMIT; |
Usuários, papéis e privilégios
| O que faz | SQL |
|---|
| Criar um papel com login | CREATE ROLE app LOGIN PASSWORD 'change-me'; |
| Acesso somente leitura a uma tabela | GRANT SELECT ON users TO app; |
| Acesso de leitura a todas as tabelas de um schema | GRANT SELECT ON ALL TABLES IN SCHEMA public TO app; |
| Revogar um privilégio | REVOKE SELECT ON users FROM app; |
| Alterar uma senha | ALTER ROLE app PASSWORD 'new-secret'; |
| Mostrar o usuário atual | SELECT current_user; |
Manutenção e monitoramento
| O que faz | SQL |
|---|
| Consultas em execução | SELECT pid, state, query FROM pg_stat_activity WHERE state <> 'idle'; |
| Cancelar uma consulta | SELECT pg_cancel_backend(12345); |
| Encerrar uma conexão | SELECT pg_terminate_backend(12345); |
| Tamanho de uma tabela com seus índices | SELECT pg_size_pretty(pg_total_relation_size('orders')); |
| Tamanho do banco de dados | SELECT pg_size_pretty(pg_database_size(current_database())); |
| Atualizar as estatísticas do planejador | ANALYZE orders; |
| Recuperar linhas mortas | VACUUM orders; |
| Reescrever uma tabela no tamanho mínimo (bloqueia a tabela) | VACUUM FULL orders; |
| Mostrar uma configuração | SHOW work_mem; |
| Alterar uma configuração nesta sessão | SET work_mem = '64MB'; |
Backup e restauração
Comandos de shell das ferramentas cliente do PostgreSQL.
| O que faz | Comando |
|---|
| Fazer dump de um banco de dados em um arquivo SQL | pg_dump -U postgres shop > shop.sql |
| Fazer dump no formato personalizado | pg_dump -Fc -U postgres shop > shop.dump |
| Fazer dump de uma tabela | pg_dump -t orders shop > orders.sql |
| Restaurar um dump SQL | psql -d shop -f shop.sql |
| Restaurar um dump em formato personalizado | pg_restore -d shop shop.dump |
| Fazer dump de todos os bancos e papéis | pg_dumpall > cluster.sql |
| Exportar uma consulta para CSV (pelo psql) | \copy (SELECT * FROM orders) TO 'orders.csv' CSV HEADER |
| Importar um CSV (pelo psql) | \copy orders (user_id, amount, status) FROM 'orders.csv' CSV HEADER |
Cada comando do psql e cada instrução PostgreSQL que você usa, em tabelas prontas para copiar e colar: primeiro a conexão e os comandos \d, depois tabelas, upserts, JSONB, datas, funções de janela, índices, papéis, backups e manutenção.
O SQL aqui usa a sintaxe do PostgreSQL 17, e a maior parte também funciona em versões anteriores. As instruções SQL foram verificadas no PostgreSQL 17; para testar uma, cole-a no playground de PostgreSQL, que vem com tabelas de exemplo.