banco-sync-cli

banco-sync-cli é um utilitário CLI em Node.js projetado para manter seus arquivos locais de migração/criação SQL em perfeita sincronia com o estado atual de um banco de dados PostgreSQL. Ele utiliza a API do Gemini (gemini-2.5-flash) para analisar as diferenças de estrutura e atualizar os arquivos em tempo real, exibindo um diff colorido no terminal (no estilo git diff) antes de salvar as alterações.

Recursos

• Suporte Exclusivo a PostgreSQL: Coleta metadados de tabelas, colunas, tipos de dados, nulidade, chaves primárias e valores padrões.
• Integração com Gemini API: Usa o modelo gemini-2.5-flash com saídas em JSON estruturado para garantir modificações de esquema precisas, preservando comentários, formatação e estilo dos arquivos originais.
• Diff Visual Colorida: Exibe modificações em verde (adições) e vermelho (remoções) com trechos de contexto antes de aplicar as mudanças.
• Armazenamento Seguro: Armazena as credenciais e chaves de API na pasta Home do usuário (~/.banco-sync-cli/config.json) indexadas pelo caminho absoluto do projeto, prevenindo vazamentos acidentais em repositórios Git.

Instalação e Execução

Como a ferramenta foi estruturada para ser executada via npx, você pode executá-la diretamente no diretório do projeto:

# Executar a CLI a partir do diretório raiz
npx . <comando>

Comandos

1. login

Configura ou atualiza as credenciais do banco de dados PostgreSQL, a chave de API do Gemini e a pasta de migrações SQL.

Você pode executar o login de forma interativa (respondendo às perguntas na tela):

npx . login

Ou de forma não-interativa passando parâmetros por linha de comando. Se todos os parâmetros obrigatórios forem fornecidos, os prompts interativos serão ignorados:

npx . login \
  --host "meu-ip-ou-host" \
  --port 5432 \
  --user "meu_usuario" \
  --password "minha_senha" \
  --database "meu_banco" \
  --schema "public" \
  --gemini-api-key "MINHA_API_KEY_DO_GEMINI" \
  --sql-folder "caminho/da/pasta/migrations"

Opções do Comando login:

• --host <host>: IP ou Host de conexão do PostgreSQL.
• --port <port>: Porta de conexão (Padrão: 5432).
• --user <user>: Usuário do banco (Padrão: postgres).
• --password <password>: Senha de acesso ao banco.
• --database <database>: Nome do banco de dados PostgreSQL.
• --schema <schema>: Schema do banco a ser lido (Padrão: public).
• --ssl: Adiciona esta flag caso a conexão precise de criptografia SSL (desabilitada por padrão).
• --gemini-api-key <key>: Chave de acesso à API do Gemini.
• --sql-folder <folder>: Caminho relativo ou absoluto da pasta que contém seus arquivos .sql.

2. sync

Conecta-se ao banco de dados configurado, extrai a estrutura do banco e compara os arquivos SQL definidos.

npx . sync

Fluxo do Comando sync:

1. Seleção de arquivos: Pergunta se você deseja sincronizar todos os arquivos da pasta configurada ou apenas um específico.
2. Coleta de Esquema: Conecta ao PostgreSQL e lê a estrutura atual.
3. Análise do Gemini: Compara o arquivo .sql com o esquema do banco de dados. O Gemini analisa e atualiza o conteúdo do arquivo mantendo apenas a sintaxe que já existia (por exemplo, adicionando uma nova coluna a uma tabela existente).
4. Exibição do Diff: Mostra um preview visual no terminal das alterações propostas (linhas adicionadas e removidas).
5. Confirmação: Solicita sua autorização final (Y/n) para escrever as atualizações diretamente no arquivo local.