Se fazer backup traz paz de espírito, ter a certeza de que você sabe restaurar esse backup é o que realmente garante uma boa noite de sono. Na nossa série Guia de Sobrevivência: Backup e Manutenção no Postgres, já vimos como extrair dados com precisão cirúrgica. Hoje, vamos inverter o fluxo.

Quando você usa os formatos Custom (-F c) ou Directory (-F d) no pg_dump, você não gera um simples amontoado de comandos SQL. Você gera um arquivo de arquivo binário inteligente. E a ferramenta definitiva para ler e restaurar esse arquivo é o pg_restore.

Neste post, vamos perder o medo do pg_restore. Você vai aprender a abrir o “capô” de um arquivo de backup, extrair apenas o que te interessa e gerenciar aqueles erros irritantes de objetos que já existem no banco de destino.

O Comando Certo para o Formato Certo

Antes de digitar o primeiro comando, uma regra de ouro que confunde muita gente:

• Se o seu backup foi gerado em Plain Text (texto puro, formato .sql), você usa o utilitário psql para restaurar.
• Se o seu backup foi gerado em Custom (.dump / .backup) ou Directory, você obrigatoriamente usa o pg_restore.

Como o nosso foco hoje é a flexibilidade avançada, vamos focar no pg_restore.

Espionando o Backup: Como listar o conteúdo com -l

Imagine que você recebeu um arquivo chamado backup_producao.dump de 50GB. Você não sabe quais tabelas estão ali dentro e precisa apenas de uma chamada configuracoes_sistema.

Em vez de restaurar tudo para descobrir, você pode listar o índice de conteúdos (TOC – Table of Contents) do arquivo usando a flag -l:

Bash

pg_restore -l backup_producao.dump > indice_banco.txt

Abra o arquivo indice_banco.txt no seu editor de texto. Você verá linhas parecidas com isto:

Plaintext

215; 1259 TABLE public clientes postgres
216; 1259 TABLE public configuracoes_sistema postgres
217; 1259 TABLE public pedidos postgres

Restauração Cirúrgica: Selecionando objetos com -L

Agora vem a mágica. Se você quiser restaurar apenas a tabela de configurações, você pode usar esse arquivo de índice como um filtro.

1. Abra o arquivo indice_banco.txt.
2. Apague ou comente (adicionando um ponto e vírgula ; ou dois traços -- no início da linha) todas as linhas dos objetos que você NÃO quer restaurar. Deixe sem comentário apenas a linha da tabela configuracoes_sistema.
3. Salve o arquivo (vamos chamá-lo de filtro_restore.txt).

Agora, passe esse filtro para o pg_restore usando a flag -L:

Bash

pg_restore -U postgres -h localhost -d meu_banco_desenvolvimento -L filtro_restore.txt backup_producao.dump

Pronto! O pg_restore vai ler o arquivo de 50GB, ignorar todo o resto e extrair exclusivamente o que você mandou.

O Gancho: Gerenciando Conflitos de Objetos Existentes

Você vai rodar um restore em um banco de homologação que já tem tabelas criadas. Se você simplesmente rodar o comando padrão, a tela vai virar uma avalanche de erros vermelhos: “relation já existe”, “erro: tabela tal já existe”.

Para gerenciar esses conflitos de forma elegante sem ter que apagar o banco manualmente, o pg_restore nos dá duas flags salvadoras:

1. Limpando a área com --clean (-c)

A flag -c diz ao pg_restore: “Antes de criar qualquer objeto (tabela, view, index), rode um comando DROP para apagar o que já existe lá”.

Bash

pg_restore -U postgres -h localhost -d meu_banco -c backup_producao.dump

2. O Par Perfeito: --clean --if-exists

O problema do --clean sozinho é que, se a tabela não existir no banco de destino (por ser um banco novo, por exemplo), o Postgres vai lançar um erro reclamando que tentou apagar algo que não existia.

Para resolver isso, junte o --if-exists:

Bash

pg_restore -U postgres -h localhost -d meu_banco -c --if-exists backup_producao.dump

Com essa combinação, o comportamento fica perfeito:

• Se a tabela existir no destino: Ele apaga (DROP TABLE IF EXISTS) e recria com os dados do backup.
• Se a tabela não existir: Ele ignora o aviso de drop e simplesmente cria a tabela.

Cheat Sheet do pg_restore (Comandos mais usados)

Aqui está o resumo dos parâmetros essenciais para você salvar no seu bloco de notas:

Bash

# Restaurar um banco inteiro limpando os dados antigos com segurança
pg_restore -U usuario -h localhost -d nome_banco -c --if-exists -v backup.dump

# Restaurar apenas a estrutura (DDL), ignorando os dados (útil para testes rápidos)
pg_restore -U usuario -h localhost -d nome_banco --schema-only backup.dump

# Restaurar apenas os dados (DML), assumindo que as tabelas vazias já existem
pg_restore -U usuario -h localhost -d nome_banco --data-only backup.dump

Conclusão

Perder o medo do pg_restore é uma questão de entender que os formatos binários do Postgres trabalham a seu favor. Saber ler o índice de um backup (-l) e aplicar filtros (-L) te dá total controle sobre o ambiente, poupando tempo crítico em momentos de manutenção.

Mas e se o problema for o relógio correndo contra você? Se você tiver um banco de centenas de gigabytes fora do ar e precisar que o restore termine o mais rápido possível para evitar prejuízo?

No próximo post, vamos falar de infraestrutura pesada: como tunar o PostgreSQL e usar paralelismo para fazer um restore gigante rodar na velocidade da luz. Não perca!

E aí, você já conhecia o truque de editar o arquivo de índice (-L) para restaurar o banco parcialmente? Deixe seu comentário ou dúvida aqui embaixo!