pgschema - gerenciamento de esquemas PostgreSQL em estilo declarativo, como no Terraform

pgschema é uma ferramenta de linha de comando (CLI) para trabalhar com esquemas de bancos de dados PostgreSQL em um estilo declarativo, semelhante à abordagem do Terraform.
Ela permite descrever o estado desejado do esquema do banco de dados em forma de código e aplicar automaticamente as alterações para alinhar o banco existente a esse estado.

A ferramenta simplifica o gerenciamento de migrações, eliminando a necessidade de escrever scripts SQL manualmente e rastrear versões de alterações.
O pgschema analisa automaticamente a diferença entre o esquema atual e o esquema desejado, gera um plano de alterações e o aplica em uma transação segura.

Para que serve o pgschema

pgschema ajuda a:

• automatizar o processo de atualização de esquemas PostgreSQL;
• implementar a abordagem "Database as Code";
• integrar o gerenciamento de esquemas em pipelines de CI/CD;
• controlar alterações de esquema via Git (pull request, revisão, rollback);
• simplificar o gerenciamento de bancos de dados multi-tenant.

Instalação

1. Baixe o arquivo binário do repositório oficial no GitHub.
2. Extraia o arquivo e adicione o binário ao PATH.
3. Verifique a instalação com o comando:
   pgschema --version

Comandos principais

1. Remoção do dump do esquema

O comando salva o estado atual do esquema no arquivo schema.sql.
Esse arquivo pode ser editado manualmente — adicionar tabelas, campos, índices, etc.

2. Planejamento das alterações

A ferramenta compara o estado atual do banco de dados com o arquivo de esquema e exibe um plano de alterações:

3. Aplicação das alterações

O pgschema aplicará o plano e executará todas as consultas DDL necessárias (por exemplo, ALTER TABLE).

Vantagens

• Abordagem declarativa – não é necessário escrever migrações manualmente, basta editar o estado desejado.
• Sem tabela de versões – o pgschema analisa automaticamente as diferenças entre o banco e o esquema.
• Suporte a CI/CD e GitOps – os esquemas podem ser armazenados no repositório e gerar planos de alterações em pull requests.
• Transacionalidade – todas as alterações são aplicadas em uma única transação, reduzindo o risco de falhas.
• Suporte a esquemas multi-tenant – permite gerenciar múltiplos esquemas ou clientes.

Desvantagens

• Sem suporte oficial para Windows – requer WSL ou container.
• Sem rollback clássico – o pgschema não mantém histórico de migrações, portanto, o desfazer de alterações deve ser manual.
• Necessita disciplina – o arquivo de esquema deve estar sempre sincronizado com o estado real do banco.
• Compatibilidade limitada – suporta PostgreSQL 14–17.

Conclusão

pgschema é uma ferramenta moderna voltada para DevOps e engenheiros que implementam infraestrutura de banco de dados como código. Ela simplifica o gerenciamento de esquemas, garante transparência e reprodutibilidade das alterações. Para equipes que trabalham com PostgreSQL em ambientes de nuvem, o pgschema é uma alternativa conveniente a sistemas de migração clássicos como Flyway ou Liquibase.

FAQ

• O que fazer se o esquema for alterado manualmente?
  O pgschema detectará as diferenças na próxima execução e sugerirá atualizar o banco ou o arquivo de esquema. É recomendável evitar alterações manuais.
• É possível usar a ferramenta com vários bancos de dados?
  Sim. O pgschema suporta múltiplos esquemas e bancos - basta definir diferentes conexões e arquivos.
• É seguro aplicar alterações em produção?
  Sim, desde que você use plan antes de apply e revise as operações DDL. Sempre teste previamente em um ambiente de staging.
• O pgschema pode ser usado em CI/CD?
  Sim. Ele se integra facilmente ao pipeline:
  passo 1 – gerar o plano (pgschema plan);
  passo 2 – revisar o plano;
  passo 3 – aplicar (pgschema apply --auto-approve).