pastebin/MIGRATION_SQL_GUIDE.md

Guia de Migração via Arquivo SQL

Visão Geral

Este guia descreve como migrar dados do BoltDB para SQLite3 usando arquivos SQL com comandos INSERT. Esta abordagem oferece mais controle e transparência no processo de migração.

Vantagens da Migração via SQL

1. Transparência: Você pode ver exatamente quais dados serão migrados
2. Controle: Pode editar o arquivo SQL antes de aplicar
3. Reversibilidade: Pode aplicar a migração múltiplas vezes
4. Auditoria: Arquivo SQL serve como log da migração
5. Flexibilidade: Pode aplicar em diferentes bancos

Processo de Migração

Passo 1: Gerar Arquivo SQL

Windows (PowerShell)

# Executar script de migração
powershell -ExecutionPolicy Bypass -File scripts/migrate-to-sql.ps1

Linux/Mac (Bash)

# Tornar script executável
chmod +x scripts/migrate-to-sql.sh

# Executar script de migração
./scripts/migrate-to-sql.sh

Manual (Go)

# Compilar e executar manualmente
go build -o migrate-to-sql cmd/migrate-to-sql/main.go
./migrate-to-sql -bolt data/yasuc.db -output data/migration.sql

Passo 2: Verificar Arquivo SQL

O arquivo gerado terá a estrutura:

-- Script de migração do BoltDB para SQLite3
-- Gerado automaticamente em 29/08/2025 09:34:37

-- Criar tabela se não existir
CREATE TABLE IF NOT EXISTS pastes (
    short_id TEXT PRIMARY KEY,
    content TEXT NOT NULL,
    content_hash TEXT NOT NULL,
    created_at INTEGER NOT NULL
);

-- Criar índices
CREATE INDEX IF NOT EXISTS idx_pastes_content_hash ON pastes(content_hash);
CREATE INDEX IF NOT EXISTS idx_pastes_created_at ON pastes(created_at);

-- Inserir dados migrados
INSERT OR IGNORE INTO pastes (short_id, content, content_hash, created_at) VALUES ('HNlNSpd', 'conteúdo do paste...', 'hash_sha256', 1756470877);

-- Resumo da migração:
-- Total de pastes processados: 80
-- Pastes únicos inseridos: 80
-- Duplicatas ignoradas: 0
-- Arquivo gerado em: 29/08/2025 09:34:37

Passo 3: Aplicar Migração

Windows (PowerShell)

# Aplicar migração automática (usa arquivo mais recente)
powershell -ExecutionPolicy Bypass -File scripts/apply-migration.ps1

# Ou especificar arquivo específico
powershell -ExecutionPolicy Bypass -File scripts/apply-migration.ps1 "data/migration_20250829_093437.sql"

Linux/Mac (Bash)

# Tornar script executável
chmod +x scripts/apply-migration.sh

# Aplicar migração automática
./scripts/apply-migration.sh

# Ou especificar arquivo específico
./scripts/apply-migration.sh data/migration_20250829_093437.sql

Manual (SQLite3)

# Aplicar diretamente com sqlite3
sqlite3 data/yasuc.sqlite3 < data/migration_20250829_093437.sql

Estrutura do Arquivo SQL

Cabeçalho

• Comentários com data/hora de geração
• Comandos CREATE TABLE e CREATE INDEX
• Instruções de uso

Dados Migrados

• Comandos INSERT OR IGNORE para cada paste
• IDs curtos únicos gerados automaticamente
• Hash SHA-256 para detecção de duplicatas
• Timestamp de criação

Resumo

• Estatísticas da migração
• Contadores de pastes processados
• Informações sobre duplicatas

Características da Migração

Geração de IDs Curtos

• 7 caracteres: Letras maiúsculas, minúsculas e números
• Únicos: Verificação contra IDs já utilizados
• Aleatórios: Geração não sequencial

Detecção de Duplicatas

• Hash SHA-256: Calculado do conteúdo de cada paste
• Mapeamento: Hash → ID curto para pastes idênticos
• Ignorar: Duplicatas não geram novos INSERTs

Tratamento de Conteúdo

• Escape de aspas: Aspas simples escapadas para SQL
• Preservação: Conteúdo original mantido intacto
• Encoding: Suporte a caracteres especiais

Verificação da Migração

Verificar Estatísticas

-- Contar total de pastes
SELECT COUNT(*) FROM pastes;

-- Verificar tamanho total
SELECT SUM(LENGTH(content)) FROM pastes;

-- Verificar alguns pastes
SELECT short_id, substr(content, 1, 50) FROM pastes LIMIT 5;

Verificar Duplicatas

-- Verificar se há duplicatas por conteúdo
SELECT content_hash, COUNT(*) as count 
FROM pastes 
GROUP BY content_hash 
HAVING count > 1;

Verificar Índices

-- Verificar índices criados
SELECT name, sql FROM sqlite_master WHERE type = 'index';

Troubleshooting

Problemas Comuns

Erro: "database is locked"

# Verificar se não há outro processo usando o banco
# Fechar aplicações que possam estar usando o SQLite3

Erro: "no such table"

# Verificar se o arquivo SQL contém CREATE TABLE
# Aplicar novamente o arquivo SQL

Erro: "disk full"

# Verificar espaço em disco
# Considerar limpar dados antigos antes da migração

Erro: "file too large"

# Dividir arquivo SQL em partes menores
# Usar streaming para arquivos muito grandes

Logs e Debugging

Verificar Progresso

# Verificar tamanho do arquivo SQL
ls -lh data/migration_*.sql

# Verificar conteúdo do arquivo
head -20 data/migration_*.sql
tail -10 data/migration_*.sql

Verificar Banco SQLite3

# Verificar integridade do banco
sqlite3 data/yasuc.sqlite3 "PRAGMA integrity_check;"

# Verificar estatísticas
sqlite3 data/yasuc.sqlite3 "SELECT COUNT(*) as total FROM pastes;"

Backup e Segurança

Backup Automático

• Scripts fazem backup automático do banco existente
• Arquivo de backup com timestamp
• Preservação de dados originais

Verificação de Integridade

# Verificar se backup foi criado
ls -la data/yasuc.sqlite3.backup.*

# Restaurar backup se necessário
cp data/yasuc.sqlite3.backup.* data/yasuc.sqlite3

Exemplos de Uso

Migração Completa

# 1. Gerar arquivo SQL
./scripts/migrate-to-sql.sh

# 2. Verificar arquivo gerado
head -20 data/migration_*.sql

# 3. Aplicar migração
./scripts/apply-migration.sh

# 4. Verificar resultado
sqlite3 data/yasuc.sqlite3 "SELECT COUNT(*) FROM pastes;"

Migração com Verificação

# 1. Gerar SQL
./scripts/migrate-to-sql.sh

# 2. Editar arquivo SQL se necessário
nano data/migration_*.sql

# 3. Aplicar com backup
./scripts/apply-migration.sh

# 4. Testar aplicação
./yasuc -db data/yasuc.sqlite3 -port 8080

Migração Incremental

# 1. Fazer backup do banco atual
cp data/yasuc.sqlite3 data/yasuc.sqlite3.backup

# 2. Gerar SQL apenas de novos dados
# (modificar script para filtrar por data)

# 3. Aplicar migração incremental
./scripts/apply-migration.sh

Considerações de Performance

Para Bancos Grandes

• Memória: Script usa memória proporcional ao número de pastes
• Tempo: Migração pode levar alguns minutos para bancos grandes
• Arquivo: Arquivo SQL pode ser muito grande

Otimizações

• Batch processing: Processar em lotes para bancos muito grandes
• Streaming: Usar streaming para evitar carregar tudo na memória
• Compression: Comprimir arquivo SQL se necessário

Próximos Passos

Após a migração bem-sucedida:

1. Testar aplicação: Verificar se tudo funciona corretamente
2. Verificar dados: Confirmar que todos os pastes foram migrados
3. Limpar backups: Remover arquivos temporários se necessário
4. Documentar: Registrar detalhes da migração