Gerador de Comando pg_dump

pg_dump em profundidade: formatos, dump paralelo e estratégia de restore

O pg_dump é o utilitário de backup lógico do PostgreSQL. Diferente do base backup binário, ele captura uma representação SQL consistente de uma base — schema, dados, índices, constraints, sequences, donos, privilégios — que qualquer servidor PostgreSQL compatível consegue replicar. A forma geral é pg_dump [opções] db_name > out.sql. Internamente ele usa uma transação REPEATABLE READ longa, então leituras e escritas concorrentes não ficam bloqueadas; o snapshot é consistente no instante em que o dump começa.

Formatos de saída: escolha com cuidado

A flag -F escolhe um de quatro formatos e a decisão tem consequências reais:

-F p   plain SQL          texto, grande, restore via psql.
-F c   custom             binário comprimido, permite restore
                          paralelo e seletivo. RECOMENDADO.
-F d   directory          dump paralelizável (-j) E restore paralelo;
                          um arquivo por relação. Melhor para DB grande.
-F t   tar                tar do formato directory; uso menos comum.

Use -F c para praticamente todo backup. Comprime, permite restore seletivo via pg_restore -t tabela e o pg_restore paraleliza o load de dados. Use -F d -j 4 quando precisa de dump paralelo em base grande.

Flags de conexão e seleção

• -h host, -p porta, -U user, -W (pede senha), -d dbname.
• -f arquivo — saída em arquivo (omita para gravar em stdout e usar em pipe).
• --schema-only / -s — só DDL.
• --data-only / -a — só dados (INSERT/COPY).
• --clean + --if-exists — emite DROP IF EXISTS antes de cada CREATE.
• --no-owner — remove declarações de ownership (útil para restore com role diferente).
• --no-privileges — remove GRANTs.
• -t schema.tabela — dumpa só tabelas específicas (repetível, aceita padrões).
• -n schema — só um schema; --exclude-schema, --exclude-table para o inverso.
• -j JOBS — workers paralelos (só com -F d).
• --compress=9 — nível de compressão (formatos custom/directory).
• --encoding=UTF8 — encoding explícito do cliente.

Restore: pg_restore vs psql

O comando de restore depende do formato do dump:

# Formato custom ou directory -> pg_restore
pg_restore -d mydb -j 4 backup.dump
pg_restore -d mydb -t users backup.dump        # só uma tabela
pg_restore -l backup.dump > toc.list           # listar objetos
pg_restore -L toc.list -d mydb backup.dump     # restore seletivo

# SQL puro -> psql
psql -d mydb -f backup.sql
psql -d mydb < backup.sql

# Dump do cluster inteiro (roles, tablespaces, todos os DBs)
pg_dumpall > cluster.sql
psql -f cluster.sql postgres

O pg_dumpall é o superset: roles, tablespaces, configuração de replicação e cada banco. Use em migrações no nível do cluster; para backup rotineiro de uma base de aplicação prefira pg_dump -F c.

Exemplos comentados

# Backup diário no formato custom comprimido
pg_dump -h db.prod -U backup -F c -f /backups/mydb-$(date +%F).dump mydb

# Dump paralelo em diretório (4 workers) de base de 100 GB
pg_dump -h db.prod -U backup -F d -j 4 -f /backups/mydb.d mydb

# Só schema, pronto para subir um ambiente de staging
pg_dump --schema-only --no-owner --no-privileges mydb > schema.sql

# Stream para S3 sem arquivo local
pg_dump -F c mydb | aws s3 cp - s3://backups/mydb.dump

# Restore paralelo com 4 workers, derrubando objetos antes
pg_restore --clean --if-exists -d mydb -j 4 backup.dump

Lógico vs físico, compatibilidade de versão, ecossistema

Backup lógico (pg_dump) é portável entre versões e arquiteturas, ideal para migrações e restores seletivos. Backup físico (pg_basebackup, pgBackRest, WAL-G) copia os arquivos de dados e o WAL — muito mais rápido em bases gigantes e a única opção prática na casa dos TB, mas o restore precisa rodar na mesma versão major e arquitetura.

Regra de versão: o pg_dump pode mirar um servidor mais antigo (ele sabe como consultar de forma forward-compatible), mas o cliente deve ser maior ou igual ao servidor na dúvida — sempre rode um pg_dump pelo menos tão novo quanto o servidor. A ordem do restore também importa: dumpar com pg_dump 16 e restaurar com pg_restore 14 pode falhar. Ferramentas profissionais: pgBackRest (incremental, paralelo, restore completo em minutos), Barman, WAL-G (archiving contínuo e PITR para S3/GCS). Serviços gerenciados: AWS RDS PostgreSQL com snapshots automáticos, GCP Cloud SQL com export, Azure Database for PostgreSQL com backups.

FAQ

O dump é hot backup? Sim. O pg_dump abre um snapshot REPEATABLE READ; transações concorrentes não são afetadas e o dump enxerga uma visão consistente do instante em que o snapshot foi tirado.

Como dumpar só um schema? pg_dump -n nome_do_schema -F c mydb > schema.dump. Use -N para excluir schemas (em scripts é comum -N pg_temp_*).

Dá para paralelizar o dump? Sim — mas só com o formato directory: pg_dump -F d -j 4 -f mydb.d mydb. Os formatos plain e custom são escritos por um único worker. O pg_restore consegue paralelizar o load de dumps custom e directory via -j N.

O formato custom já comprime? Sim — por padrão zlib nível 6. Suba para --compress=9 em redes lentas. Não precisa empilhar gzip em cima.

O pg_restore segue depois de um erro? Por padrão sim e loga a falha; passe --exit-on-error para parar no primeiro erro. Combine com --single-transaction para envolver todo o restore em uma única tx (mais lento, semântica tudo-ou-nada).