Sqldef: ferramenta de gerenciamento de esquema idempotente para MySQL, PostgreSQL e SQLite

• Ferramenta baseada em CLI para gerenciar migrações de banco de dados comparando o diff entre esquemas SQL
• Permite gerenciar esquemas de RDBMS usando a sintaxe SQL DDL comum
• Suporta os principais bancos de dados, como MySQL, MariaDB, TiDB, PostgreSQL, SQL Server e SQLite3
• No site, é possível testar a comparação de esquemas e a geração de DDL por meio de uma demonstração online com build em WebAssembly
• Permite gerenciar alterações no banco de dados de forma idempotente, sendo útil para uma sincronização de esquema estável

---

Visão geral do sqldef

• O sqldef é uma ferramenta CLI que compara o diff entre dois esquemas SQL, analisa as diferenças e, com base nisso, gera comandos DDL
  • O usuário pode comparar o esquema atual com o esquema de destino e derivar automaticamente as alterações necessárias
  • É possível executar migrações usando diretamente a sintaxe SQL DDL comum
• Os bancos de dados compatíveis são MySQL, MariaDB, TiDB, PostgreSQL, SQL Server e SQLite3

Recursos da demonstração online

• O site oferece uma Online Demo, na qual é possível verificar visualmente as mudanças no esquema
  • A opção “Enable DROP” permite controlar se comandos de remoção serão incluídos
  • Na seção “Up (current → desired)”, são exibidos exemplos de DDL como adição de novas colunas, criação de índices e inclusão de constraints
  • Na seção “Down (desired → current)”, são fornecidos exemplos de mudanças reversas, como remoção de constraints

Como funciona

• A demonstração online usa o build em WebAssembly do sqldef para executar a comparação (diff) de esquemas SQL dentro do navegador
  • Ela calcula as diferenças entre dois esquemas e gera automaticamente os comandos DDL necessários como resultado
  • É possível verificar o código-fonte do build em WebAssembly pelo link do repositório no GitHub

[GN⁺]

Comentários no Hacker News

• Se você quiser uma cobertura mais abrangente para Postgres, talvez valha a pena dar uma olhada no pgschema que eu criei
  No verão passado eu achava que ele estava bem completo, mas depois de corrigir mais de 100 issues relatadas por usuários ao longo de 6 meses, percebi o quanto eu era ingênuo

  • Ferramenta muito legal. Pretendemos fazer uma PoC com o nosso time
    Fico curioso se ela também oferece suporte para verificar divergências entre vários clusters de banco de dados
  • Lembra o Migra
  • Parece bom para migração de esquema, mas fico curioso sobre como lida com update/insert quando é preciso mover os dados de fato
  • O pg_roll da Xata também pode ser uma alternativa a considerar

• Testei com SQLite, e em migrações mais complicadas para adicionar restrições de chave estrangeira a tabelas existentes ele gera SQL inválido
  Por exemplo, uma instrução como ALTER TABLE books ADD CONSTRAINT fk_books_author FOREIGN KEY (author_id) REFERENCES authors (id) não é permitida no SQLite
  Veja a documentação relacionada em SQLite ALTER TABLE

  • Então no fim, para adicionar uma chave estrangeira, a situação é ter que remover a coluna e adicioná-la de novo?

• Eu uso Atlas
  Tanto a abordagem baseada em migrações quanto a baseada em esquema têm prós e contras, então uso as duas no mesmo projeto
  A baseada em esquema acelera o desenvolvimento, e a baseada em migrações permite deploys mais confiáveis

  • Sou Ariel, da equipe do Atlas. É comum combinar uma abordagem declarativa no ambiente local com uma abordagem versionada nos ambientes reais
    Como o Atlas gera automaticamente as migrações no PR, a maioria dos desenvolvedores nem precisa lidar diretamente com o workflow versionado
    Documentação relacionada: Declarative vs Versioned Workflows, Atlas Action
  • Eu também estava olhando o sqldef e outras alternativas quando encontrei o Atlas
    Gostei do suporte explícito a migration flow. Quero saber exatamente quais mudanças serão aplicadas antes do deploy de verdade

• Fico curioso se existe alguma boa ferramenta que ofereça suporte a migrações em background
  Por exemplo, adicionar uma coluna nullable temporária em uma tabela grande, deixar o código novo começar a gravar nela, preencher os dados antigos em lotes no background e no final mudar para non-nullable
  Seria ótimo ter uma ferramenta que permitisse expressar essas mudanças procedurais de forma declarativa e revisá-las e testá-las junto com o código
  Hoje isso geralmente é tratado com scripts temporários e instruções manuais de deploy

  • Eu costumo escrever as migrações de esquema manualmente, mas uso principalmente o grate
    É simples de configurar no ambiente de desenvolvimento, e há exemplos como FastEndpoints-SqlJobQueues

• Essa ferramenta é realmente muito legal
  Graças a ela posso abandonar meu projeto hobby que tentava criar a mesma funcionalidade
  Em vez disso, vou começar um projeto novo lidando com outro problema já resolvido umas 100 vezes — por exemplo, uma ferramenta simples para monitorar logs do systemd e enviar erros por e-mail

• Fiquei feliz em ver que isso não é só mais um gerenciador de migração, e sim uma ferramenta pequena e útil
  Passa a sensação de complementar bem as limitações do SQL. Também me faz pensar que seria bom se fosse declarativo como o DDL do Spanner
  No Postgres, tento manter os scripts de esquema idempotentes. Começo com CREATE TABLE IF NOT EXISTS e, ao adicionar novas colunas, deixo ALTER separado
  Mas com o tempo os scripts ficam complexos, e quando tudo estabiliza eu limpo as instruções ALTER
  Se eu precisar restaurar um backup antigo, uma ferramenta assim provavelmente ajudaria a alinhar a compatibilidade rapidamente

• Fico curioso sobre como isso se compara com Entity Framework ou sqitch/liquibase
  Entendo a abordagem declarativa, mas em bancos de dados grandes de produção as migrações não são algo simplesmente declarativo
  Um gerenciador de esquema ideal precisa entender custo de query e estratégias para minimizar downtime
  Adicionar colunas ou alterar índices pode causar varreduras completas na tabela

  • O problema maior é que os próprios dados podem fazer parte da migração
    Por exemplo, se você dividir Fullname em FirstName e LastName, um diff simples expressa só metade da mudança
    No EF Core, os métodos Up/Down lidam com transformações reversíveis
    Fico curioso sobre como isso trata transformações de dados sem esse conceito

• Nós criamos internamente uma ferramenta de transformação baseada em XML
  Como XML é mais fácil de fazer parse do que SQL, ela compara o esquema definido no XML com o banco e aplica só as mudanças necessárias
  Usávamos Sybase SQLAnywhere, e havia a complexidade de, ao adicionar ou remover colunas quando materialized views estavam envolvidas, ter que recriar as views e os índices
  Então colocamos salvaguardas para permitir remoção de colunas apenas de forma explícita, e mudanças de tipo só quando fossem seguras
  Isso tornou as migrações muito simples em centenas de ambientes on-premises instalados
  Basta alterar o XML que a ferramenta cuida do resto, e ainda podemos adicionar recursos quando necessário

• No SQLite, o tratamento de remoção de colunas não funciona bem
  Só nas versões recentes foi adicionado DROP COLUMN, mas na maioria dos dispositivos isso ainda não é suportado
  No exemplo, foi adicionado x integer not null e tentado um DROP, mas só apareceu a mensagem “-- Skipped”
  O método padrão é criar uma tabela temporária, copiar os dados e depois substituir, mas essa ferramenta não automatiza isso
  Como é uma parte fácil de errar quando há restrições envolvidas, isso decepciona um pouco
  No fim, se ela só resolve as tarefas fáceis, dá a sensação de que é melhor fazer manualmente

• Essa ferramenta parece útil apenas com bancos de dados vazios
  Ela não consegue lidar com migração de dados e, por exemplo, em casos como transformar uma coluna JSONB em uma estrutura mais organizada ou gerar ADD COLUMN … NOT NULL numa migração reversa depois de remover uma coluna, não dá para usá-la em tabelas reais com dados