docs: Add comprehensive documentation and helper scripts

Add: - QUICKSTART.md: 5-minute quick start guide with examples - scripts/incus_setup.sh: Automated PostgreSQL container setup - scripts/validate_migration.sql: SQL validation queries - scripts/setup_cron.sh: Cron job setup for incremental migrations - tests/test_setup.py: Unit tests for configuration and transformation - install.sh: Quick installation script Documentation includes: - Step-by-step setup instructions - Example queries for RAWDATACOR and ELABDATADISP - Troubleshooting guide - Performance optimization tips 🤖 Generated with Claude Code Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2025-12-10 19:58:20 +01:00
parent 62577d3200
commit fccc83eb74
6 changed files with 662 additions and 0 deletions
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -0,0 +1,275 @@
+# Quick Start Guide
+
+Guida rapida per iniziare con il migration tool.
+
+## Setup in 5 minuti
+
+### 1. Clonare e configurare
+
+```bash
+# Entrare nella directory
+cd mysql2postgres
+
+# Creare environment
+python -m venv venv
+source venv/bin/activate
+
+# Installare dipendenze
+pip install -e .
+```
+
+### 2. Configurare .env
+
+```bash
+# Copiare template
+cp .env.example .env
+
+# Editare con le tue credenziali
+nano .env
+```
+
+**Esempio .env:**
+```env
+MYSQL_HOST=localhost
+MYSQL_PORT=3306
+MYSQL_USER=root
+MYSQL_PASSWORD=mypassword
+MYSQL_DATABASE=production_db
+
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=pgpassword
+POSTGRES_DATABASE=migrated_db
+
+BATCH_SIZE=10000
+LOG_LEVEL=INFO
+```
+
+### 3. Creare PostgreSQL in Incus
+
+```bash
+# Creare container Incus
+incus launch images:ubuntu/22.04 pg-server
+
+# Accedere al container
+incus shell pg-server
+
+# Dentro il container:
+apt update && apt install -y postgresql postgresql-contrib
+
+# Avviare PostgreSQL
+systemctl start postgresql
+systemctl enable postgresql
+
+# Uscire dal container
+exit
+
+# Ottenere IP del container
+incus list
+# Anota l'IP e usalo in POSTGRES_HOST nel .env
+```
+
+### 4. Eseguire migrazione
+
+```bash
+# Verificare configurazione
+python main.py info
+
+# Creare schema
+python main.py setup --create-schema
+
+# Migrare tutti i dati
+python main.py migrate full
+
+# Verificare risultati
+python main.py migrate incremental  # Dovrebbe dire "No new rows"
+```
+
+### 5. Eseguire benchmark
+
+```bash
+python main.py benchmark
+```
+
+## Comandi Frequenti
+
+### Migrazione iniziale
+```bash
+# Dry-run (vedere cosa verrebbe fatto)
+python main.py migrate full --dry-run
+
+# Effettiva migrazione
+python main.py migrate full
+
+# Solo una tabella
+python main.py migrate full --table RAWDATACOR
+```
+
+### Migrazioni periodiche
+```bash
+# Migrare solo i cambiamenti dal last sync
+python main.py migrate incremental
+
+# Con stato personalizzato
+python main.py migrate incremental --state-file daily_sync.json
+```
+
+### Benchmark
+```bash
+# Benchmark di default (5 iterazioni)
+python main.py benchmark
+
+# Con più iterazioni
+python main.py benchmark --iterations 20
+
+# Con output personalizzato
+python main.py benchmark --output my_results.json
+```
+
+## Esempi di Query su PostgreSQL
+
+Dopo la migrazione, puoi interrogare i dati in PostgreSQL:
+
+### RAWDATACOR
+
+```sql
+-- Tutti i dati per un'unità
+SELECT * FROM rawdatacor
+WHERE unit_name = 'Unit1'
+LIMIT 10;
+
+-- Filtrare per valore di una misura
+SELECT id, event_date, event_time,
+       measurements->'0'->>'value' as val0,
+       measurements->'0'->>'unit' as val0_unit
+FROM rawdatacor
+WHERE measurements ? '0'
+AND (measurements->'0'->>'value')::NUMERIC > 10.0;
+
+-- Aggregazione per data
+SELECT event_date, COUNT(*) as record_count
+FROM rawdatacor
+WHERE event_date >= '2024-01-01'
+GROUP BY event_date
+ORDER BY event_date;
+
+-- Statistiche per unità e strumento
+SELECT unit_name, tool_name_id, COUNT(*) as total_records
+FROM rawdatacor
+GROUP BY unit_name, tool_name_id
+ORDER BY total_records DESC;
+```
+
+### ELABDATADISP
+
+```sql
+-- Dati con velocità
+SELECT id_elab_data, event_date, event_time,
+       (measurements->'kinematics'->>'speed')::NUMERIC as speed,
+       (measurements->'kinematics'->>'acceleration')::NUMERIC as acceleration
+FROM elabdatadisp
+WHERE measurements @> '{"kinematics": {}}'
+LIMIT 10;
+
+-- Filtro su intervallo
+SELECT unit_name, COUNT(*) as count
+FROM elabdatadisp
+WHERE (measurements->'kinematics'->>'speed')::NUMERIC > 5.0
+GROUP BY unit_name;
+
+-- Media velocità per unità
+SELECT unit_name,
+       AVG((measurements->'kinematics'->>'speed')::NUMERIC) as avg_speed,
+       MAX((measurements->'kinematics'->>'speed')::NUMERIC) as max_speed
+FROM elabdatadisp
+WHERE event_date >= '2024-01-01'
+GROUP BY unit_name;
+
+-- Dati con errore di calcolo
+SELECT * FROM elabdatadisp
+WHERE calc_err > 0
+AND event_date >= '2024-01-01'
+ORDER BY event_date DESC;
+```
+
+## Monitorare Progress
+
+Il tool mostra una progress bar durante la migrazione:
+
+```
+Migrating RAWDATACOR █████████████░░░░░░░░░░░░░░░░░░░░░ 45% 00:05:23
+```
+
+I log sono salvati in:
+- Console: Output di default
+- File: `.log` (configurabile)
+
+## Troubleshooting
+
+### "Cannot connect to MySQL"
+```bash
+# Verificare che MySQL sia online
+mysql -h localhost -u root -p -e "SELECT 1"
+```
+
+### "Table does not exist in PostgreSQL"
+```bash
+# Ricreate lo schema
+python main.py setup --create-schema
+```
+
+### "Migration is slow"
+```bash
+# Aumentare batch size in .env
+BATCH_SIZE=50000
+
+# Oppure ottimizzare MySQL
+mysql> FLUSH PRIVILEGES;
+```
+
+### "Benchmark queries fail"
+```bash
+# Verificare che le tabelle siano state migrate
+SELECT COUNT(*) FROM rawdatacor;
+
+# Verificare JSONB è valido
+SELECT measurements FROM rawdatacor LIMIT 1;
+```
+
+## Prossimi Passi
+
+1. **Validare i dati**
+   ```bash
+   # Contare righe in entrambi i database
+   # MySQL
+   mysql> SELECT COUNT(*) FROM RAWDATACOR;
+
+   # PostgreSQL
+   psql> SELECT COUNT(*) FROM rawdatacor;
+   ```
+
+2. **Testare query critiche**
+   - Assicurarsi che le query dell'applicazione funzionino su PostgreSQL
+
+3. **Benchmark performance**
+   ```bash
+   python main.py benchmark --iterations 20
+   ```
+
+4. **Setup migrazioni periodiche**
+   - Schedulare `python main.py migrate incremental` con cron/systemd timer
+
+5. **Mantenimento indici**
+   ```sql
+   -- Analizzare tabelle
+   ANALYZE rawdatacor;
+   ANALYZE elabdatadisp;
+
+   -- Reindex se necessario
+   REINDEX TABLE rawdatacor;
+   ```
+
+## Support
+
+Per domande o problemi, consulta il file README.md completo.