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

Bancos de dados

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

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

Observação: o pgschema oferece suporte oficial para Linux e macOS. No Windows, pode ser executado via WSL.

Comandos principais

1. Remoção do dump do esquema

PGPASSWORD=pass pgschema dump \

--host localhost \

--db mydb \

--user postgres \

--schema public > schema.sql

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

PGPASSWORD=pass pgschema plan \

--host localhost \

--db mydb \

--user postgres \

--schema public \

--file schema.sql \

--output-human stdout \

--output-json plan.json

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

Plano: 1 para modificar.

Resumo por tipo:

tabelas: 1 para modificar

Tabelas:

~ usuários

+ idade (coluna)

3. Aplicação das alterações

PGPASSWORD=pass pgschema apply \

--host localhost \

--db mydb \

--user postgres \

--schema public \

--plan plan.json \

--auto-approve

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).