Posted on: November 27, 2025 06:39 PM
Posted by: Renato
Categories: postgresql Docker
Views: 72
📝 Artigo: Gerenciamento e Restauração de Bancos de Dados PostgreSQL com Docker e pg_dump/pg_restore
📝 Artigo: Gerenciamento e Restauração de Bancos de Dados PostgreSQL com Docker e pg_dump/pg_restore
Introdução
Este artigo sumariza os passos essenciais para gerenciar (backup, restauração, limpeza) um banco de dados PostgreSQL contido em um container Docker, utilizando as poderosas ferramentas nativas do PostgreSQL: pg_dump e pg_restore. O foco principal é garantir que os backups sejam criados de forma segura e que os processos de restauração sejam bem-sucedidos e limpos.
1. O Desafio da Restauração (Aviso implied data-only restore)
Muitas vezes, ao tentar restaurar um backup, o usuário se depara com o aviso: pg_restore: implied data-only restore.
pg_restore: connecting to database for restore
pg_restore: implied data-only restore
Este aviso não é um erro, mas uma indicação de que o arquivo de backup (.backup ou similar) não continha as definições de esquema (comandos CREATE TABLE, CREATE FUNCTION, etc.). O utilitário pg_restore automaticamente assume que você deseja restaurar apenas os dados (--data-only ou -a) nas tabelas que já existem.
Solução: Se o objetivo é restaurar tudo (esquema e dados), o backup original deve ser refeito, garantindo que o esquema seja incluído.
2. 🛡️ Criação de um Backup Seguro com pg_dump
Para evitar problemas de esquema e garantir uma restauração flexível e limpa, o backup deve ser gerado com flags específicas. O formato mais recomendado é o Custom (-F c) devido à sua compressão e flexibilidade de restauro seletivo.
O comando é executado a partir da máquina local, mas aponta para o serviço PostgreSQL dentro do container (trial_wms_postgres):
Bash
docker exec -t trial_wms_postgres pg_dump -U postgres -F c -Z 9 --clean postgres > trial.backup
| Flag | Função | Benefício |
-F c |
Formato Custom (binário). | Permite compressão e restauro seletivo. Mais flexível. |
-Z 9 |
Nível de compressão 9. | Reduz o tamanho do arquivo e o tempo de transferência/armazenamento. |
--clean |
Inclui comandos DROP. |
Garante que o banco de dados de destino será limpo antes de recriar os objetos. |
3. 🧹 Limpeza e Recriação do Banco de Dados
Antes de qualquer restauração completa, especialmente após tentativas falhas, é uma boa prática excluir (DROP) e recriar o banco de dados de destino. Isso garante que não haja objetos residuais que possam interferir no processo.
Importante: Não é possível dropar um banco de dados enquanto se está conectado a ele. Deve-se conectar ao banco de dados padrão de manutenção (template1).
Bash
# 1. Excluir o banco de dados 'postgres'
docker exec -it trial_wms_postgres psql -U postgres -d template1 -c "DROP DATABASE postgres;"
# 2. Recriar o banco de dados 'postgres' com o mesmo proprietário
docker exec -it trial_wms_postgres psql -U postgres -d template1 -c "CREATE DATABASE postgres OWNER postgres;"
4. 🔄 Restauração do Novo Backup
Com o banco de dados limpo e o backup em formato Custom (-F c) com esquema incluído, a restauração é realizada com pg_restore.
O comando redireciona a entrada do arquivo local (< trial.backup) para o pg_restore em execução dentro do container:
Bash
docker exec -i trial_wms_postgres pg_restore -U postgres -v -d postgres --clean < trial.backup
-
-i: Essencial nodocker execpara permitir a entrada de dados via pipe. -
--clean: Utiliza os comandosDROPque foram incluídos no backup (pelopg_dump --clean) para garantir uma restauração limpa. -
-v: Verbose mode, que mostra todos os objetos sendo criados e restaurados.
5. ⚠️ Restauração de Backups em Formato SQL
Se o backup foi gerado no formato plain text (um arquivo .sql que pode ser aberto em um editor de texto), o utilitário correto a ser usado é o psql, não o pg_restore:
Bash
docker exec -i trial_wms_postgres psql -U postgres -d postgres < arquivo.sql
Este guia abrangente permite o gerenciamento completo e seguro de backups de PostgreSQL em ambientes conteinerizados com Docker.
| Flag | Descrição | Por que usar? |
-F t |
Formato Tar. | Melhor do que o formato "plain text" para portabilidade, mas o custom format (-F c) é ainda mais flexível para restauro. |
-U postgres |
Usuário. | Garante que o usuário com privilégios máximos seja usado para evitar erros de permissão. |
-Z 9 |
Compressão (Compression level 9). | Segurança de armazenamento: Comprime o backup ao máximo (nível 9), economizando espaço e tempo de transferência. |
--inserts |
Insere dados linha por linha. | Segurança na Restauração: Cria comandos INSERT em vez de um único COPY, o que facilita a restauração em um ambiente com restrições de permissão. |
--if-exists |
Adiciona IF EXISTS nas instruções DROP. |
Restauro mais seguro: Previne erros se a tabela ou objeto não existir no banco de dados de destino. |
--clean |
Adiciona comandos DROP antes dos CREATE. |
Limpeza garantida: Assegura que o banco de dados de destino será limpo de objetos antigos antes de carregar os novos. |
Donate to Site
Renato
Developer