Liquibase Helper - Extensão VS Code

🗄️ Automação Inteligente para Scripts Liquibase 🚀

Sistema de configuração seguro • IDs únicos garantidos • Interface moderna

A extensão definitiva para simplificar a criação e organização de scripts Liquibase!

Automatiza a criação de estruturas Liquibase padronizadas, numeração sequencial de scripts, geração de changelogs XML compatíveis com Liquibase, e sistema avançado de configuração que nunca commita suas configurações locais.

🚀 Funcionalidades Principais

✨ Interface Gráfica Intuitiva

Webview integrada ao VS Code com formulários organizados
Upload de arquivos SQL via drag & drop ou seleção
Editor de texto para digitação direta de scripts
Validação em tempo real de campos obrigatórios
Feedback visual de sucesso/erro nas operações

🔢 Numeração Automática Inteligente

Sequenciamento automático: 01-, 02-, 03-... dentro da branch
Detecção de scripts existentes para continuar numeração
IDs únicos de changeset com detecção de colisão e timestamps (YYYYMMDD-HHMM)
Prevenção absoluta de conflitos entre desenvolvedores
Ordenação automática de tags no changelog master

📁 Organização Automática por Branch

Detecção automática da branch Git atual com fallback inteligente
Criação automática de pasta baseada no nome da branch
Remoção inteligente de prefixos gitflow (feature/, hotfix/, bugfix/, etc.)
Remoção de sufixos -task para nomes mais limpos
Múltiplos scripts por branch com numeração sequencial

🔄 Gestão Completa de Changelog

Geração automática de changelog.xml para cada branch
Atualização automática do changelog master com ordenação
Estrutura Liquibase padrão (changeset + tag)
Inclusão automática de scripts de rollback
Endereçamento relativo dos arquivos SQL
IDs únicos garantidos com sistema de detecção de colisão

⚙️ Sistema de Configuração Seguro

Configurações NUNCA commitadas - Sistema próprio fora do repositório
Configuração de autor global para todos os projetos
Configurações específicas por projeto sem poluir o Git
Caminhos personalizáveis para diretórios Liquibase
Interface de configuração integrada ao VS Code
Hash único por projeto para identificação segura

📦 Instalação

Via VS Code Marketplace (Método Recomendado)

Abra o VS Code
Vá para Extensions (Ctrl+Shift+X)
Pesquise por: Liquibase Helper
Clique em "Install"

Via Command Line

# Instalar diretamente via código do marketplace
code --install-extension fulano-dev.liquibase-helper

Via Arquivo .vsix (Desenvolvimento)

Baixe a extensão:
- Acesse os Releases do GitHub
- Baixe o arquivo liquibase-helper-1.1.0.vsix
Instale no VS Code:
```
code --install-extension liquibase-helper-1.1.0.vsix
```
Ou pelo VS Code:
- Ctrl+Shift+P → "Extensions: Install from VSIX..."
- Selecione o arquivo baixado

🎯 Como Usar

1. Abra um projeto com Git no VS Code

A extensão detecta automaticamente a branch Git atual.

2. Configure a extensão (primeira vez):

Ctrl+Shift+P → "Liquibase: Configurar Liquibase Helper"
Autor Padrão: Seu nome/usuário (aparecerá nos changesets)
Diretório do Liquibase: Caminho relativo onde estão os changelogs (ex: src/main/resources/db/changelog)
Changelog Master: Caminho do arquivo master (ex: src/main/resources/db/changelog/db.changelog-master.xml)

3. Execute a extensão:

Ctrl+Shift+P → "Liquibase: Abrir Liquibase Helper"
Ou use o comando: liquibase-helper.start

4. Crie seus scripts usando a interface:

📋 Formulário Principal:

Nome do Script: Digite um nome descritivo (ex: criar-tabela-usuarios)
Comentário: Descrição do que o script faz
Conteúdo SQL: Cole ou digite o script SQL principal
Rollback SQL: Cole ou digite o script de rollback

📁 Upload de Arquivos:

Use "Carregar Arquivo SQL" para fazer upload de arquivos .sql
Use "Carregar Arquivo Rollback" para fazer upload do rollback

✅ Criação:

Clique em "Criar Scripts" para gerar toda a estrutura automaticamente

5. Resultado Automático:

✅ Pasta criada baseada na branch atual
✅ Scripts numerados sequencialmente
✅ Changelog.xml gerado
✅ Master changelog atualizado

📁 Estrutura Gerada

Para uma branch feature/20250731-criar-usuarios, a extensão criará automaticamente:

src/main/resources/db/changelog/
├── changesets/
│   └── 20250731-criar-usuarios/              # Pasta baseada na branch
│       ├── 01-criar-tabela-usuarios.sql      # Script principal numerado
│       ├── 01-criar-tabela-usuarios.rollback.sql  # Script de rollback
│       ├── 02-adicionar-indices.sql          # Próximo script (se houver)
│       ├── 02-adicionar-indices.rollback.sql
│       └── changelog.xml                     # Changelog da branch
└── db.changelog-master.xml                   # Master atualizado automaticamente

📋 Exemplo de changelog.xml gerado:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" 
                   xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" 
                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext 
                                       http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
                                       http://www.liquibase.org/xml/ns/dbchangelog 
                                       http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.5.xsd">

  <!-- Script SQL Principal -->
  <changeSet id="20250731-1430" author="joao.dev"> 
    <comment>Script para criar tabela de usuários</comment> 
    <sqlFile path="01-criar-tabela-usuarios.sql" relativeToChangelogFile="true" endDelimiter="~" /> 
    <rollback>
      <sqlFile path="01-criar-tabela-usuarios.rollback.sql" relativeToChangelogFile="true" endDelimiter="~" /> 
    </rollback>
  </changeSet>

  <!-- Tag para versionamento -->
  <changeSet id="20250731-1431" author="joao.dev">
    <tagDatabase tag="20250731-criar-usuarios" />
  </changeSet>
</databaseChangeLog>

🏷️ Características dos IDs Gerados:

Formato: YYYYMMDD-HHMM (ex: 20250731-1430)
Único por execução: Baseado no timestamp exato com detecção de colisão
Sequencial por branch: Scripts numerados 01-, 02-, 03-...
Zero conflitos: Sistema avançado de prevenção de IDs duplicados
Ordenação automática: Tags ordenadas corretamente no changelog master

```

⚙️ Sistema de Configuração Avançado

A extensão possui um sistema revolucionário de configuração que garante que suas configurações locais NUNCA sejam commitadas para o repositório Git, eliminando conflitos e vazamentos de configuração.

🔒 Como Funciona:

Configurações do Autor: Salvas nas configurações globais do VS Code
Configurações do Projeto: Salvas em ~/.vscode-liquibase-helper/project-[hash].json
Hash Único: Cada projeto tem um hash único baseado no caminho absoluto
Zero Commits: Impossível commitar configurações por acidente

🔧 Como Configurar:

Via Interface da Extensão (Recomendado):
- Ctrl+Shift+P → "Liquibase: Open"
- Preencha os campos na seção "Configuração"
- Clique em "Salvar Configuração"
Via Configurações do VS Code (Author apenas):
- Ctrl+, → Abrir configurações
- Buscar por "Liquibase Helper"
- Configurar apenas o Author (configuração global)

📂 Localização das Configurações:

Tipo	Localização	Commitado?	Descrição
Author	VS Code Global Settings	❌ Não	Nome que aparece nos changesets
Projeto	`~/.vscode-liquibase-helper/`	❌ Não	Caminhos específicos do projeto
Workspace	`.vscode/settings.json`	⚠️ Evitado	A extensão não usa mais

📋 Parâmetros de Configuração:

Campo	Localização	Descrição	Exemplo
`liquibaseHelper.author`	Global VS Code	Nome que aparece no campo `author` dos changesets	`"joao.dev"`
`liquibaseDirectory`	Arquivo local	Diretório onde estão os changelogs (relativo à raiz)	`"src/main/resources/db/changelog"`
`masterChangelogPath`	Arquivo local	Caminho completo do changelog master	`"src/main/resources/db/changelog/db.changelog-master.xml"`

💡 Vantagens do Sistema:

✅ Zero Vazamentos: Configurações nunca vão para o repositório
✅ Configuração Global de Author: Configure uma vez, use em todos os projetos
✅ Configurações Específicas por Projeto: Cada projeto mantém suas próprias configurações
✅ Segurança Total: Impossível commitar configurações por engano
✅ Portabilidade: Trabalhe em múltiplos projetos sem conflitos
✅ Hash Único: Sistema inteligente de identificação de projetos
✅ Backup Automático: Configurações preservadas mesmo se mover o projeto

🔄 Migração Automática:

Se você estava usando uma versão anterior, a extensão migra automaticamente suas configurações do workspace para o novo sistema seguro na primeira execução.

🛠️ Desenvolvimento

Estrutura do Projeto

src/
├── extension.ts              # 📍 Ponto de entrada e ativação da extensão
├── helpers/
│   ├── configUtils.ts        # ⚙️ Sistema avançado de configuração segura
│   ├── fileUtils.ts          # 📁 Criação de arquivos com IDs únicos e detecção de colisão
│   └── gitUtils.ts           # 🔗 Utilitários Git com formatação inteligente de branches
└── webview/
    └── ui.ts                 # 🎨 Interface webview com separação de configurações

⚡ Executar em Modo de Desenvolvimento

Clone e prepare o projeto:

git clone https://github.com/fulano-dev/liquibase-helper.git
cd liquibase-helper
npm install

Abra no VS Code e execute:
- Abra o projeto no VS Code
- Pressione F5 para iniciar o modo debug
- Uma nova janela do VS Code será aberta (Extension Development Host)
- Execute o comando Liquibase: Abrir Liquibase Helper

🔨 Scripts Disponíveis

npm run compile      # Compila TypeScript para JavaScript
npm run watch        # Compila em modo watch (auto-recompila)
npm run package      # Cria arquivo .vsix para distribuição
npm run install-local  # Instala extensão localmente

📦 Criar Pacote para Distribuição

# Compilar o projeto
npm run compile

# Gerar arquivo .vsix
npm run package

# Resultado: liquibase-helper-1.1.0.vsix

# Publicar no marketplace (se você tem acesso)
npx vsce publish

🚨 Troubleshooting

❌ Erro: "Cannot find module 'path'"

Solução:

# Instale as dependências do projeto
npm install

❌ Erro: "Configurações não estão sendo salvas"

Causa: Problema com permissões no diretório home ou configuração corrompida.

Soluções:

Verifique permissões de escrita no diretório ~/.vscode-liquibase-helper/
Execute o VS Code como administrador se necessário

Delete o arquivo de configuração e reconfigure:

Remove-Item -Path "~/.vscode-liquibase-helper/project-*.json" -Force

❌ Erro: "IDs de changeset duplicados"

Causa: Muito raro, mas pode ocorrer se múltiplos desenvolvedores criarem scripts no mesmo minuto.

Soluções:

A extensão detecta automaticamente colisões e incrementa o timestamp
Se persistir, aguarde 1 minuto e tente novamente
Verifique se não há scripts com IDs manuais conflitantes

❌ Erro: "Branch atual não encontrada"

Causa: A extensão não conseguiu detectar a branch Git automaticamente.

Soluções:

Certifique-se de que o projeto está em um repositório Git
Execute git status para verificar se há uma branch ativa
A extensão usa fallback automático para tentar detectar via API do VS Code

❌ Erro: "Changelog master não encontrado"

Causa: O arquivo de changelog master configurado não existe.

Soluções:

Verifique se o caminho em liquibaseDirectory está correto
Verifique se o arquivo masterChangelogPath existe

Crie o arquivo master manualmente se necessário:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog">
</databaseChangeLog>

❌ Extensão não aparece no Command Palette

Soluções:

Verifique se a instalação foi bem-sucedida
Reinicie o VS Code completamente
Verifique se não há erros no console: Help > Toggle Developer Tools
Certifique-se de ter um workspace aberto (a extensão só funciona com projetos abertos)

❌ Interface não carrega / Webview em branco

Soluções:

Verifique o console do VS Code para erros JavaScript
Reinicie o VS Code
Execute Developer: Reload Window (Ctrl+Shift+P)

❌ Numeração de scripts incorreta

Causa: Scripts existentes na pasta não seguem o padrão esperado.

Solução:

A extensão procura por arquivos no formato XX-*.sql (ex: 01-, 02-)
Renomeie scripts existentes para seguir esse padrão se necessário

🆘 Obtendo Ajuda Adicional

Console de Desenvolvimento:
- Help > Toggle Developer Tools
- Verifique a aba "Console" para erros detalhados
Logs da Extensão:
- View > Output
- Selecione "Log (Window)" no dropdown para ver logs do VS Code
Reportar Problemas:
- GitHub Issues
- Inclua informações sobre: SO, versão do VS Code, logs de erro

🤝 Contribuição

Contribuições são sempre bem-vindas! Aqui está como você pode ajudar:

🐛 Reportando Bugs

Acesse GitHub Issues
Verifique se o bug já foi reportado
Crie uma nova issue com:
- Descrição detalhada do problema
- Passos para reproduzir
- Versão do VS Code e SO
- Screenshots se aplicável

💡 Sugerindo Melhorias

Abra uma Feature Request
Descreva a funcionalidade desejada
Explique como isso melhoraria a extensão

🔧 Contribuindo com Código

Fork o projeto
Clone seu fork localmente

Crie uma branch para sua feature:

git checkout -b feature/minha-nova-funcionalidade

Faça suas modificações e teste

Commit suas mudanças:

git commit -m "Adiciona nova funcionalidade X"

Push para sua branch:

git push origin feature/minha-nova-funcionalidade

Abra um Pull Request no GitHub

📋 Guidelines para Contribuição

Use TypeScript para todo código novo
Siga as convenções de código existentes
Adicione comentários para lógica complexa
Teste suas mudanças antes de enviar
Atualize documentação se necessário

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

📝 Resumo da Licença MIT:

✅ Uso comercial permitido
✅ Modificação permitida
✅ Distribuição permitida
✅ Uso privado permitido
❌ Nenhuma garantia fornecida
❌ Nenhuma responsabilidade assumida

📞 Suporte e Contato

GitHub: fulano-dev/liquibase-helper
Issues: Reportar problemas
Email: joao@fulano.dev

Feito com ❤️ para a comunidade de desenvolvedores