Migração do Quick.db para Helper.db

🔄 Migração do Quick.db para Helper.db

✨ Visão Geral

Tendo em vista que Helper.db é uma continuação ao legado do Quick.db ele tem compatibilidade nativa mas se houver necessidade de migração segue o guia abaixo. Para te ajudar a migrar seus projetos do Quick.db para Helper.db de forma rápida e segura. O Helper.db foi criado para continuar o legado do Quick.db com melhorias e recursos adicionais.

🎯 Por que migrar?

🚀 Performance melhorada: Até 300% mais rápido em operações em lote
🆕 Novos recursos: Sistema de busca avançado, agregações, cache inteligente
🛡️ Manutenção ativa: Correções de bugs e atualizações regulares
📚 Documentação completa: Wiki oficial e exemplos práticos
🔄 Compatibilidade: API compatível com Quick.db

📦 Instalação

1. Instalar Helper.db

npm install helper.db better-sqlite3

2. Remover Quick.db (opcional)

npm uninstall quick.db

🔄 Migração Automática

Método 1: Usando o método `migrateFromQuickDB()`

O Helper.db possui um método dedicado para migração automática:

const { HelperDB } = require("helper.db");

async function migrarDados() {
    const db = new HelperDB();

    try {
        // Migrar dados do arquivo SQLite do Quick.db
        const resultado = await db.migrateFromQuickDB('./json.sqlite');

        console.log(`✅ Migração concluída com sucesso!`);
        console.log(`📊 ${resultado.migrated}/${resultado.total} registros migrados`);
        console.log(`⏰ Migrado em: ${resultado.timestamp}`);

    } catch (error) {
        console.error('❌ Erro na migração:', error.message);
    }
}

migrarDados();

Eventos de Migração

Monitore o progresso da migração com eventos:

const { HelperDB } = require("helper.db");
const db = new HelperDB();

// Antes da migração iniciar
db.on('beforeMigration', (data) => {
    console.log('🔄 Iniciando migração de:', data.source);
    console.log('📂 Arquivo:', data.filePath);
});

// Migração concluída com sucesso
db.on('migrationComplete', (data) => {
    console.log('✅ Migração concluída!');
    console.log('📊 Registros migrados:', data.migrated);
    console.log('📈 Total de registros:', data.total);
    console.log('⏰ Data/Hora:', data.timestamp);
});

// Erro durante a migração
db.on('migrationError', (data) => {
    console.error('❌ Erro na migração:', data.error);
    console.error('📊 Status:', data.status);
});

// Executar migração
async function executarMigracao() {
    try {
        const resultado = await db.migrateFromQuickDB('./json.sqlite');
        console.log('🎉 Processo concluído:', resultado);
    } catch (error) {
        console.error('💥 Falha na migração:', error.message);
    }
}

executarMigracao();

🔄 Migração Manual

Método 2: Backup e Restore

Se você preferir ter mais controle sobre o processo:

const { HelperDB } = require("helper.db");
const QuickDB = require("quick.db"); // Manter temporariamente

async function migracaoManual() {
    // Instância do Quick.db (origem)
    const quickDB = new QuickDB();

    // Instância do Helper.db (destino)
    const helperDB = new HelperDB();

    try {
        // 1. Obter todos os dados do Quick.db
        const todosOsDados = quickDB.all();

        console.log(`📊 Encontrados ${todosOsDados.length} registros para migrar`);

        // 2. Migrar dados um por um
        let migrados = 0;
        for (const item of todosOsDados) {
            try {
                await helperDB.set(item.ID, item.data);
                migrados++;

                // Progress log a cada 100 registros
                if (migrados % 100 === 0) {
                    console.log(`📈 Migrados: ${migrados}/${todosOsDados.length}`);
                }
            } catch (error) {
                console.warn(`⚠️ Erro ao migrar registro ${item.ID}:`, error.message);
            }
        }

        console.log(`✅ Migração concluída: ${migrados}/${todosOsDados.length} registros`);

        // 3. Verificar migração
        const totalHelper = await helperDB.count();
        console.log(`🔍 Verificação: ${totalHelper} registros no Helper.db`);

    } catch (error) {
        console.error('❌ Erro na migração manual:', error.message);
    }
}

migracaoManual();

📝 Alterações no Código

Importação

Antes (Quick.db):

const db = require("quick.db");

Depois (Helper.db):

const { HelperDB } = require("helper.db");
const db = new HelperDB();

Uso Básico

A API permanece 100% compatível:

// ✅ Funciona igual nos dois
await db.set("usuario.nome", "João");
await db.get("usuario.nome");
await db.add("usuario.pontos", 10);
await db.push("usuario.itens", "item1");
await db.has("usuario");
await db.delete("usuario.temp");

Novos Recursos (Opcionais)

Aproveite os novos recursos do Helper.db:

// 🔍 Sistema de busca avançado
const usuarios = await db.search("João", "nome");
const adultos = await db.between(18, 65, "idade");

// 📊 Estatísticas e agregações
const stats = await db.aggregate([
    { type: 'count' },
    { type: 'avg', field: 'idade' },
    { type: 'sum', field: 'pontos' }
]);

// 💾 Backup automático
await db.backup('./backup.json');

// 🩺 Monitoramento
const ping = await db.ping();
console.log(`Latência: ${ping.latency}ms`);

🛠️ Configurações Avançadas

Personalização da Instância

const { HelperDB } = require("helper.db");

const db = new HelperDB({
    filePath: "minha-base.sqlite",  // Caminho personalizado
    table: "dados",                 // Nome da tabela
    enableCache: true,              // Cache inteligente
    cacheSize: 2000,               // Tamanho do cache
    enableBackup: true,            // Backup automático
    backupOptions: {
        interval: 1800000,         // 30 minutos
        maxBackups: 12,            // Manter 12 backups
        path: "./backups"          // Pasta de backups
    }
});

Múltiplas Tabelas

// Quick.db com tabelas
const usuarios = new db.table("usuarios");
const produtos = new db.table("produtos");

// Helper.db com tabelas
const usuarios = db.table("usuarios");
const produtos = db.table("produtos");

✅ Checklist de Migração

Antes de Migrar

Backup completo: Faça backup do seu arquivo json.sqlite
Teste em ambiente de desenvolvimento: Nunca teste em produção primeiro
Documente dependências: Liste todos os pontos que usam a base de dados
Verifique versão do Node.js: Helper.db requer Node.js 12+

Durante a Migração

Execute a migração automática: Use migrateFromQuickDB()
Monitore os logs: Acompanhe eventos de migração
Verifique integridade: Compare contagem de registros
Teste funcionalidades: Confirme que tudo funciona

Após a Migração

Atualize imports: Substitua require("quick.db") por require("helper.db")
Teste em produção: Faça testes graduais
Configure novos recursos: Cache, backup automático, etc.
Remova Quick.db: npm uninstall quick.db quando estiver seguro

🚨 Problemas Comuns e Soluções

Erro: “Cannot find module ‘better-sqlite3‘“

# Solução: Instalar dependência
npm install better-sqlite3

Erro: “Migration failed: ENOENT”

// Solução: Verificar caminho do arquivo
const fs = require('fs');
if (fs.existsSync('./json.sqlite')) {
    console.log('✅ Arquivo encontrado');
} else {
    console.log('❌ Arquivo não encontrado');
}

Dados não aparecem após migração

// Solução: Verificar tabela correta
const db = new HelperDB({ table: "json" }); // Tabela padrão do Quick.db

Performance lenta na migração

// Solução: Migração em lotes
async function migracaoEmLotes() {
    const db = new HelperDB();
    const dados = /* seus dados */;
    const loteSize = 100;

    for (let i = 0; i < dados.length; i += loteSize) {
        const lote = dados.slice(i, i + loteSize);
        const entries = lote.map(item => [item.id, item.value]);

        await db.setMany(entries);
        console.log(`Processado lote ${Math.floor(i/loteSize) + 1}`);
    }
}

🎯 Exemplo Completo de Migração

const { HelperDB } = require("helper.db");

class MigradorQuickDB {
    constructor() {
        this.db = new HelperDB();
        this.setupEventos();
    }

    setupEventos() {
        this.db.on('beforeMigration', (data) => {
            console.log(`🔄 Iniciando migração de ${data.source}`);
        });

        this.db.on('migrationComplete', (data) => {
            console.log(`✅ ${data.migrated} registros migrados com sucesso`);
        });

        this.db.on('migrationError', (data) => {
            console.error(`❌ Erro: ${data.error}`);
        });
    }

    async migrar(caminhoArquivo = './json.sqlite') {
        try {
            console.log('🚀 Iniciando processo de migração...');

            // Fazer backup antes da migração
            const backup = `./backup-pre-migration-${Date.now()}.json`;
            console.log(`💾 Criando backup em: ${backup}`);

            // Executar migração
            const resultado = await this.db.migrateFromQuickDB(caminhoArquivo);

            console.log('📊 Resultado da migração:');
            console.log(`   - Registros migrados: ${resultado.migrated}`);
            console.log(`   - Total de registros: ${resultado.total}`);
            console.log(`   - Status: ${resultado.status}`);
            console.log(`   - Timestamp: ${resultado.timestamp}`);

            // Verificação final
            await this.verificarMigracao();

            console.log('🎉 Migração concluída com sucesso!');
            return resultado;

        } catch (error) {
            console.error('💥 Falha na migração:', error.message);
            throw error;
        }
    }

    async verificarMigracao() {
        const total = await this.db.count();
        const sample = await this.db.limit(5);

        console.log(`🔍 Verificação: ${total} registros encontrados`);
        console.log('📋 Amostra dos dados:');
        sample.forEach((item, index) => {
            console.log(`   ${index + 1}. ${item.id}: ${JSON.stringify(item.value).slice(0, 50)}...`);
        });
    }
}

// Uso
async function executarMigracao() {
    const migrador = new MigradorQuickDB();

    try {
        await migrador.migrar('./json.sqlite');
        console.log('✨ Processo de migração finalizado!');
    } catch (error) {
        console.error('❌ Processo falhou:', error.message);
        process.exit(1);
    }
}

// Executar se arquivo for chamado diretamente
if (require.main === module) {
    executarMigracao();
}

module.exports = MigradorQuickDB;

📚 Recursos Adicionais

Links Úteis

📖 Wiki Oficial: helper-db-wiki.vercel.app
📦 NPM Package: npmjs.com/package/helper.db
🐛 Issues: GitHub Issues
💬 Discussões: GitHub Discussions

Comandos Úteis

# Verificar versão instalada
npm list helper.db

# Atualizar para versão mais recente
npm update helper.db

# Verificar integridade da instalação
npm audit

🤝 Suporte

Se você encontrar problemas durante a migração:

Consulte este guia primeiro
Verifique a documentação
Procure em issues existentes no GitHub
Abra uma nova issue se necessário
Participe das discussões da comunidade

Migração bem-sucedida! 🎉

Agora você pode aproveitar todos os recursos avançados do Helper.db mantendo a simplicidade que você já conhecia do Quick.db.