Como o PostgreSQL armazena dados: estrutura do banco e o log de transações (WAL)

Quando você mexe num banco de dados, tudo parece bem simples: adicionou uma linha, atualizou um registro, deletou um cliente. Mas por trás dessa simplicidade tem um mecanismo bem complexo e pensado. Onde esses dados ficam de verdade? Como o PostgreSQL consegue não perder nada, mesmo se o servidor cair do nada?

Pra sacar isso, tem que entender duas coisas chave: onde os dados ficam fisicamente (tabelas, índices, info de sistema) e como funciona o esquema de proteção desses dados — o log de transações, ou seja, o WAL (Write-Ahead Logging).

O banco de dados inteiro do PostgreSQL fica guardado como um monte de arquivos numa pasta especial — data_directory. Normalmente ela fica aqui:

/var/lib/postgresql/17/main

Nessa pasta tá o coração do banco: as tabelas, os índices, a metainfo e as configs. Lá também fica o WAL — o mecanismo que recebe todas as mudanças primeiro. Antes dos dados irem pra tabela no disco, eles são gravados no WAL. É tipo um rascunho, onde o banco anota cada passo, pra se der ruim, conseguir recuperar tudo até a última operação.

Por causa desse esquema, o PostgreSQL garante confiabilidade e resistência, mesmo nos piores cenários.

Tabelas

Cada tabela é fisicamente um arquivo separado ou um conjunto de arquivos. Esses arquivos ficam no subdiretório base/. A estrutura é mais ou menos assim:

$PGDATA/base/
├── 16384/
│   ├── 12345   ← tabela
│   ├── 12346   ← índice
│   └── ...

• 16384 — é o identificador interno do banco de dados (OID).
• 12345 — identificador da tabela específica.

Se a tabela for grande, o PostgreSQL quebra ela em segmentos de 1 GB cada:

12345
12345.1
12345.2
...

Os arquivos não têm "linhas" igual num CSV de texto — é um formato de "páginas binárias" de 8 KB.

WAL: Write-Ahead Logging — não é só um "log"

Agora bora pra uma das partes mais importantes e que a galera mais confunde no PostgreSQL — o WAL, ou Write-Ahead Logging. Apesar do nome log, o WAL não é um arquivo de log de texto comum, tipo log de erro ou de query. É um mecanismo vital de consistência e recuperação de dados, que trabalha no nível baixo das mudanças do sistema de arquivos.

O WAL não é um relatório de eventos, mas sim um registro prévio de todas as mudanças que o PostgreSQL vai fazer nos dados. Esse registro rola antes de modificar de verdade as tabelas no disco. Por isso o nome write-ahead — "escrever antes".

Quando você, por exemplo, insere uma nova linha numa tabela, o PostgreSQL:

1. NÃO atualiza a tabela no disco na hora — isso seria lento e arriscado.
2. Primeiro grava no WAL que essa linha vai ser adicionada.
3. Só depois, quando for conveniente (tipo num processo em background), os dados realmente vão pra tabela.

Funciona tipo um cheque no banco: primeiro você assina (WAL), e só depois o banco atualiza a conta (tabela). Se der ruim — o cheque ainda tá contigo, dá pra tentar de novo.

Formato e estrutura do WAL

• Os arquivos WAL são guardados em formato binário.
• Cada arquivo é um fluxo ordenado de operações, que descrevem mudanças internas nas páginas de dados, estruturas de índice, commits, etc.
• Um arquivo WAL tem tamanho fixo — por padrão, 16 MB.

Importante: o WAL não tem "comandos SQL" ou "linhas de tabela" do jeito que a gente tá acostumado. Ele tem instruções pro engine do PostgreSQL de como refazer as mudanças, página por página.

O que rola se der pau?

Se o servidor PostgreSQL desligar do nada — tipo, caiu a energia — nem tudo tá perdido. Na próxima inicialização, o banco não surta, só carrega do disco a última versão "estável" dos dados. Depois ele pega o log de transações (WAL), onde ficaram todas as últimas mudanças, e aplica elas direitinho — faz o que ainda não tinha ido pros arquivos principais. No fim, o banco volta pra um estado totalmente consistente, como se nada tivesse acontecido.

Recursos extras do WAL

Point-In-Time Recovery (PITR). Guardar os arquivos WAL permite restaurar o banco até qualquer ponto no tempo entre dois backups completos.

Replicação streaming. O PostgreSQL pode mandar registros WAL pra outro servidor em tempo real. Isso permite manter uma réplica quente — uma cópia do banco sincronizada com o principal.

Recuperação incremental. Junto com um backup completo, o WAL permite restaurar só as mudanças, sem copiar o banco inteiro de novo.

Criando backups binários: pg_basebackup

Se você já brincou um pouco com o pg_dump, sabe que ele é ótimo pra criar backups lógicos (ou seja, copiar a estrutura do banco e os dados em formato de comandos SQL). Mas e se você quiser um backup físico? Tipo, uma cópia espelhada de todos os arquivos do banco? Aí entra a ferramenta pg_basebackup.

pg_basebackup é uma utilidade pra criar cópias físicas dos dados do PostgreSQL. É especialmente útil pra bancos grandes, onde você precisa gerenciar a recuperação de forma eficiente. O principal lance do pg_basebackup é que ele faz isso rapidão.

Sintaxe básica do comando pg_basebackup

Pra usar o pg_basebackup, tem que sacar o comando dele. Você roda no terminal e o formato básico é esse:

pg_basebackup -D /backup_directory -F tar -z -P

Bora ver o que cada coisa faz:

• -D /backup_directory — diz pra onde vão os arquivos do backup.
• -F tar — formato dos dados. A opção tar cria um arquivo de backup no formato .tar. Você também pode usar plain pra criar a estrutura de arquivos do banco.
• -z — comprime o backup, economizando espaço em disco. Sempre bom quando o backup ocupa menos espaço!
• -P — mostra o progresso em tempo real. Dá aquela confiança: você vê que tá rolando e o servidor não travou.

Exemplo de uso:

pg_basebackup -D /backups/university_backup -F tar -z -P

Depois de rodar, na pasta /backups/university_backup vai ter um backup no formato .tar.

Vantagens de usar o pg_basebackup

Eficiência: backups incrementais evitam duplicar dados que não mudaram, economizando tempo e espaço.

Facilidade de uso: a ferramenta pg_basebackup cuida de tudo, incluindo os arquivos WAL.

Confiabilidade: por ser integrado com o PostgreSQL, o pg_basebackup faz cópias exatas do banco, que são fáceis de restaurar.

Exemplos de uso

Agora bora pra prática. Aqui vão exemplos reais de como usar o pg_basebackup pra criar backups do PostgreSQL. Vamos mostrar como fazer um backup básico, como ativar compressão e como incluir o arquivamento do WAL pra poder restaurar "até um ponto no tempo". Essas dicas servem tanto pra quem tá começando quanto pra cenários mais avançados.

Criando um backup básico

pg_basebackup -D /backups/full_backup -F tar -z -P

Resultado: backup completo do banco num arquivo .tar.

Configurando compressão e formato

Vamos criar um backup dos dados com compressão alta:

pg_basebackup -D /backups/full_backup -F tar -z -Z 9 -P

Aqui o -Z 9 define o nível de compressão (máximo é 9).

Arquivando o WAL

Se você configurar o arquivamento do WAL, o banco pode ser restaurado até qualquer ponto no tempo. O comando pra configurar o backup do WAL é:

pg_basebackup -D /backups/incremental_backup -F tar -z -P --wal-method=archive