Imagine a cena: o servidor de banco de dados principal falha. Sem pânico, afinal, você configurou o pg_dump perfeitamente todas as noites. Você levanta uma nova instância do PostgreSQL, prepara o comando de restauração e… BUM! Centenas de erros na tela dizendo que os usuários, permissões e roles da aplicação simplesmente não existem.

O que aconteceu? Você caiu no erro mais clássico de gerenciamento de infraestrutura Postgres.

Neste primeiro post da nossa série Guia de Sobrevivência: Backup e Manutenção no Postgres, vamos entender de vez a diferença conceitual entre o pg_dump e o pg_dumpall, quando aplicar cada um no seu pipeline e como evitar esse desastre de produção.

A Diferença Conceitual: Banco de Dados vs. Cluster

Para entender os comandos, precisamos lembrar como o PostgreSQL organiza as coisas. No topo, temos o Cluster (a instância do Postgres rodando no servidor). Dentro desse cluster, existem objetos globais e os bancos de dados individuais.

• Objetos Globais: São informações que valem para todo o servidor, como usuários (roles), senhas, permissões globais e definições de onde os dados são salvos fisicamente (tablespaces).
• Objetos Locais: São os dados do seu ecossistema em si: tabelas, esquemas, views, triggers e funções dentro de um banco específico.

+-------------------------------------------------------------+
| CLUSTER POSTGRESQL (Instância)                              |
|                                                             |
|  [ Objetos Globais: Roles/Usuários, Senhas, Tablespaces ]  |
|                                                             |
|  +-----------------------+       +-----------------------+  |
|  | BANCO DE DADOS A      |       | BANCO DE DADOS B      |  |
|  | (Tabelas, Schemas)    |       | (Tabelas, Schemas)    |  |
|  +-----------------------+       +-----------------------+  |
+-------------------------------------------------------------+

pg_dump: O Especialista

O pg_dump olha apenas para um banco de dados específico. Ele ignora completamente tudo o que está fora dele (inclusive os usuários que têm acesso a ele).

pg_dumpall: O Generalista

O pg_dumpall extrai todo o cluster. Ele passa por cada banco de dados existente na instância e, antes ou depois disso, extrai todas as configurações globais do servidor.

O Grande Erro: O Backup que não restaura sozinho

O erro que custa noites de sono para muitos SysAdmins e DEVs é achar que rodar o pg_dump do banco de dados da aplicação é o suficiente para um plano de Disaster Recovery (Recuperação de Desastres).

⚠️ O Perigo: Se o seu pg_dump gerar um arquivo perfeitamente saudável de um banco chamado ecommerce, e você tentar restaurar esse arquivo em um servidor Postgres zerado, a restauração vai falhar se as tabelas pertencerem ao usuário usr_ecommerce. O Postgres não cria o usuário magicamente a partir de um pg_dump.

Exemplos Práticos na Linha de Comando

Vamos ver como esses comandos se comportam na prática.

1. Usando o pg_dump para um banco específico

Se você precisa apenas fazer o backup do banco meu_app para manutenção ou migração local, o comando padrão é:

Bash

pg_dump -U postgres -h localhost -F c -b -v -f meu_app_backup.dump meu_app

• -F c: Define o formato como Custom (altamente recomendado, pois é compactado e flexível para restauração).
• -b: Inclui os blobs (grandes objetos binários).
• -v: Modo verbose (mostra o progresso na tela).

2. O Jeito Certo de salvar as Globais com pg_dumpall

Para garantir que você tem os usuários e senhas salvos, você pode usar o pg_dumpall com a flag --globals-only. Isso evita gerar um arquivo gigantesco com todos os dados, focando apenas na estrutura de acessos:

Bash

pg_dumpall -U postgres -h localhost --globals-only > as_roles_globais.sql

Nota: O pg_dumpall gera apenas arquivos em texto puro (SQL script), por isso usamos o redirecionador > para salvar o arquivo.

3. O Backup Total da Instância

Se a sua intenção é clonar o servidor inteiro (com todos os múltiplos bancos de dados e usuários) para uma nova máquina, aí sim usamos o pg_dumpall completo:

Bash

pg_dumpall -U postgres -h localhost > backup_total_servidor.sql

Guia Rápido de Decisão: Quando usar qual?

Cenário	Ferramenta Recomendada	Por quê?
Backup diário da aplicação principal	pg_dump	É mais rápido, gera arquivos binários compactados (-F c) e permite restauração paralela.
Rotina de Infraestrutura (DBA/DevOps)	pg_dumpall --globals-only	Essencial rodar em paralelo com o pg_dump para garantir que a criação de novos usuários na empresa seja salva.
Atualização de versão maior do Postgres (ex: v15 para v17)	pg_dumpall	Garante que absolutamente toda a estrutura do cluster antigo seja migrada sem incompatibilidades de permissões.

O Pulo do Gato para o seu Pipeline

A melhor estratégia de backup do mundo real para quem gerencia servidores de banco de dados não é escolher um ou outro, mas combinar ambos.

Em seu script de automação, configure duas tarefas:

1. Um job usando pg_dumpall --globals-only para salvar os usuários e permissões de madrugada.
2. Jobs individuais usando pg_dump -F c para cada banco de dados crítico da sua operação.

No próximo post da série, vamos entrar a fundo no pg_dump e descobrir qual é o melhor formato de arquivo para o seu cenário (e como fazer backups de tabelas gigantes usando paralelismo). Não perca!

Gostou da dica? Já passou por esse sufoco de restaurar um banco e ver erros de “role does not exist”? Deixe seu comentário abaixo!