Benvenuti alla guida di ottimizzazione delle prestazioni di HarborDB. Questa risorsa completa ti aiuterà a ottimizzare ogni aspetto del tuo flusso di lavoro PostgreSQL, dalla scrittura di query efficienti alla configurazione di HarborDB e macOS per le massime prestazioni.

Comprendere i Fattori di Prestazione

Diversi fattori influenzano le prestazioni del tuo database in HarborDB:

| Fattore | Impatto | Livello di Ottimizzazione | | ----------------------------- | ----------- | ------------------------- | | Progettazione Query | Alto | Applicazione | | Indici del Database | Alto | Database | | Connessione di Rete | Medio | Infrastruttura | | Risorse di Sistema | Medio | macOS | | Impostazioni HarborDB | Basso-Medio | Applicazione | | Configurazione PostgreSQL | Alto | Database |

Ottimizzazione delle Query

Scrivere Query Efficienti

1. Seleziona Solo Ciò di Cui Hai Bisogno

-- ❌ Inefficiente
SELECT * FROM customers;

-- ✅ Efficiente
SELECT customer_id, name, email FROM customers;

2. Usa le Clausole WHERE in Modo Efficace

-- ❌ Inefficiente (scansione completa della tabella)
SELECT * FROM orders
WHERE EXTRACT(YEAR FROM order_date) = 2024;

-- ✅ Efficiente (usa indice)
SELECT * FROM orders
WHERE order_date >= '2024-01-01'
  AND order_date < '2025-01-01';

3. Limita i Set di Risultati

-- Limita sempre quando esplori
SELECT * FROM large_table LIMIT 100;

-- Usa paginazione per risultati grandi
SELECT * FROM products
ORDER BY created_at DESC
LIMIT 50 OFFSET 0;

4. Evita Problemi di Query N+1

-- ❌ Inefficiente (query multiple)
-- Prima query: SELECT * FROM orders WHERE status = 'pending'
-- Poi per ogni ordine: SELECT * FROM customers WHERE customer_id = ?

-- ✅ Efficiente (query singola con JOIN)
SELECT o.*, c.name, c.email
FROM orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.status = 'pending';

Usare EXPLAIN per Analizzare le Query

HarborDB rende facile analizzare le prestazioni delle query:

Scrivi la tua query nell'editor
Clicca "Spiega" (⚡) nella barra degli strumenti
Rivedi il piano di esecuzione nel pannello risultati

Comprendere l'Output di EXPLAIN

Seq Scan: Scansione completa della tabella (spesso lenta per tabelle grandi)
Index Scan: Uso di un indice (di solito più veloce)
Nested Loop: Join di tabelle (controlla se appropriato)
Stime di costo: Numeri più alti significano più lavoro

Pattern Comuni di Ottimizzazione

-- Suggerimento per aggiunta indice mancante
EXPLAIN ANALYZE
SELECT * FROM orders WHERE customer_id = 1234;

-- Il risultato potrebbe mostrare: "Seq Scan on orders"
-- Soluzione: CREATE INDEX idx_orders_customer_id ON orders(customer_id);

Ottimizzazione degli Indici del Database

Quando Aggiungere Indici

Aggiungi indici per:

Chiavi primarie (indicizzate automaticamente)
Chiavi esterne (spesso richiedono indicizzazione manuale)
Colonne filtrate frequentemente
Colonne ordinate frequentemente
Colonne usate nelle condizioni JOIN

Creare Indici Efficaci

-- Indice a colonna singola
CREATE INDEX idx_orders_status ON orders(status);

-- Indice multi-colonna (l'ordine è importante!)
CREATE INDEX idx_orders_date_status ON orders(order_date, status);

-- Indice parziale (per sottoinsiemi specifici)
CREATE INDEX idx_active_users ON users(email) WHERE active = true;

-- Indice unico per vincolo
CREATE UNIQUE INDEX idx_unique_email ON users(email);

Manutenzione degli Indici

-- Controlla l'uso degli indici
SELECT schemaname, tablename, indexname
FROM pg_stat_user_indexes
WHERE idx_scan = 0;  -- Indici mai usati

-- Ricostruisci indici frammentati
REINDEX INDEX idx_orders_status;

-- Aggiorna statistiche per il pianificatore di query
ANALYZE orders;

Ottimizzazione delle Connessioni

Impostazioni del Pool di Connessioni

Ottimizza le tue connessioni HarborDB:

Apri Preferenze → Connessioni
Regola le impostazioni in base al tuo flusso di lavoro:

| Impostazione | Valore Raccomandato | Scopo | | --------------------------- | ------------------- | ------------------------------- | | Timeout Connessione | 30 secondi | Previene connessioni bloccate | | Keep-Alive | Abilitato | Mantiene connessioni inattive | | Connessioni Massime | 5-10 | Bilancia prestazioni/memoria | | Modalità SSL | Prefer | Sicuro senza sovraccarico |

Ottimizzazione di Rete

Per database remoti:

Usa tunnel SSH per connessioni sicure e ottimizzate
Abilita compressione per grandi set di risultati
Pianifica query pesanti durante ore di minor traffico
Monitora latenza di rete con strumenti integrati

-- Testa la latenza di rete
SELECT 1 as test;  -- Query semplice per misurare tempo di andata e ritorno

Impostazioni di Prestazione di HarborDB

Gestione della Memoria

Regola l'uso della memoria in Preferenze → Prestazioni:

| Impostazione | Raccomandazione | Impatto | | -------------------------- | --------------- | ------------------------------ | | Cache Query | 256 MB | Query ripetute più veloci | | Memoria Set Risultati | 512 MB | Gestisce dataset più grandi | | Modalità Streaming | Abilitata | Migliore per risultati grandi | | Auto-Aggiornamento | 30 secondi | Bilancia freschezza/prestazioni|

Ottimizzazione dell'Interfaccia

Disabilita animazioni in Preferenze → Aspetto
Riduci ritardo auto-completamento a 100ms
Limita profondità auto-espansione barra laterale
Usa modalità scura per efficienza display OLED

Scorciatoie da Tastiera per Velocità

Padroneggia questi potenziatori di produttività:

| Scorciatoia | Azione | Tempo Risparmiato | | ----------- | -------------- | ----------------- | | ⌘ + R | Esegui query | 2-3 secondi | | ⌘ + . | Annulla query | Previene attese | | ⌘ + T | Nuova scheda query | 1-2 secondi | | ⌘ + S | Salva query | 1 secondo | | ⌘ + E | Esporta risultati | 2 secondi | | ⌘ + F | Trova nella query | 3-5 secondi |

Ottimizzazione del Sistema macOS

Considerazioni Hardware

Memoria (RAM)

Minimo: 8 GB per uso base
Raccomandato: 16 GB per lavoro professionale
Ottimale: 32 GB per dataset grandi

Archiviazione (SSD)

Minimo: 256 GB spazio libero
Raccomandato: 512 GB+ per file database ed esportazioni
Usa SSD esterno per archiviazione database grandi

Processore

Apple Silicon: M1/M2/M3 ottimizzato
Intel: i5 minimo, i7/i9 raccomandato

Impostazioni macOS

Risparmio Energia (Preferenze di Sistema):
- Disabilita "Metti i dischi rigidi in pausa"
- Mantieni display acceso durante query lunghe
Activity Monitor:
- Monitora uso memoria HarborDB
- Controlla risorse processo PostgreSQL
Utility Disco:
- Assicurati che TRIM SSD sia abilitato
- Monitora salute disco e spazio libero

Comandi Terminale per Prestazioni

# Controlla risorse di sistema
top -o cpu  # Uso CPU
vm_stat     # Uso memoria
iostat      # I/O disco

# Monitora HarborDB specificamente
ps aux | grep HarborDB
lsof -p $(pgrep HarborDB) | wc -l  # File aperti

Strategie per Dataset Grandi

Lavorare con Milioni di Righe

1. Paginazione Lato Server

-- Invece di caricare tutte le righe
SELECT * FROM huge_table;

-- Usa paginazione
SELECT * FROM huge_table
ORDER BY id
LIMIT 1000 OFFSET 0;

-- Pagina successiva
SELECT * FROM huge_table
ORDER BY id
LIMIT 1000 OFFSET 1000;

2. Streaming dei Risultati

Abilita in Preferenze → Prestazioni:

✅ "Abilita streaming per risultati > 10.000 righe"
✅ "Dimensione chunk streaming: 1000 righe"
✅ "Streaming in background: Abilitato"

3. Viste Materializzate

-- Pre-calcola query costose
CREATE MATERIALIZED VIEW daily_sales_summary AS
SELECT
    DATE(order_date) as day,
    COUNT(*) as orders,
    SUM(total) as revenue
FROM orders
GROUP BY DATE(order_date);

-- Aggiorna periodicamente
REFRESH MATERIALIZED VIEW daily_sales_summary;

Ottimizzazione Esportazione

Per esportazioni grandi:

Esporta in CSV (più efficiente di JSON)
Usa esportazioni suddivise (Preferenze → Esporta)
Comprimi esportazioni automaticamente
Esporta direttamente su archiviazione esterna

Monitoraggio Prestazioni

Strumenti Integrati HarborDB

Timer Query: Mostra tempo di esecuzione nella barra di stato
Monitor Memoria: Visualizza in Finestra → Monitor Prestazioni
Stato Connessione: Metriche di rete in tempo reale
Cronologia Query: Rivedi prestazioni query passate

Query di Monitoraggio PostgreSQL

-- Query attive
SELECT
    pid,
    usename,
    query_start,
    state,
    query
FROM pg_stat_activity
WHERE state != 'idle'
ORDER BY query_start DESC;

-- Query lente
SELECT
    query,
    calls,
    total_time,
    mean_time,
    rows
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

-- Statistiche tabelle
SELECT
    schemaname,
    relname,
    seq_scan,
    idx_scan,
    n_tup_ins,
    n_tup_upd,
    n_tup_del
FROM pg_stat_user_tables
ORDER BY seq_scan DESC;

Problemi Comuni di Prestazione & Soluzioni

Problema: "La query impiega troppo tempo"

Lista di Controllo Soluzione:

[ ] Aggiungi indici appropriati
[ ] Riscrivi la query per essere più efficiente
[ ] Controlla configurazione PostgreSQL
[ ] Verifica connettività di rete
[ ] Aumenta impostazioni timeout se necessario

Problema: "HarborDB usa troppa memoria"

Passi di Soluzione:

Riduci dimensione cache query (Preferenze → Prestazioni)
Chiudi schede query non utilizzate
Riavvia HarborDB periodicamente
Controlla perdite di memoria (Activity Monitor)
Aumenta RAM di sistema se costantemente ai limiti

Problema: "Esportazione/Importazione molto lenta"

Consigli di Ottimizzazione:

Usa formato CSV invece di JSON
Disabilita scansione antivirus sulla cartella target
Esporta su SSD invece di HDD
Usa strumenti nativi PostgreSQL (pg_dump/pg_restore) per operazioni molto grandi
Dividi operazioni grandi in lotti più piccoli

Problema: "L'interfaccia sembra lenta"

Soluzioni Rapide:

Disabilita evidenziazione sintassi per query molto grandi
Riduci auto-espansione barra laterale
Usa tema UI più semplice
Chiudi altre applicazioni intensive di risorse
Riavvia HarborDB e macOS

Tecniche Avanzate di Ottimizzazione

Partizionamento Tabelle Grandi

-- Crea tabella partizionata
CREATE TABLE orders_partitioned (
    order_id BIGSERIAL,
    order_date DATE NOT NULL,
    customer_id INT,
    total DECIMAL(10,2)
) PARTITION BY RANGE (order_date);

-- Crea partizioni
CREATE TABLE orders_2024_q1 PARTITION OF orders_partitioned
    FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');

CREATE TABLE orders_2024_q2 PARTITION OF orders_partitioned
    FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');

Suggerimenti Piano Query

-- Forza uso indice (usa con cautela)
SET enable_seqscan = off;

-- Aumenta temporaneamente memoria di lavoro
SET work_mem = '64MB';

-- Usa metodo join specifico
SET enable_nestloop = off;
SET enable_hashjoin = on;

Pooling Connessioni con PGBouncer

Per applicazioni ad alta concorrenza:

Installa PGBouncer (Homebrew: brew install pgbouncer)
Configura per pooling transazioni
Connetti HarborDB attraverso PGBouncer
Monitora statistiche riutilizzo connessioni

Test delle Prestazioni

Creare Query di Benchmark

-- Testa prestazioni query
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE order_date BETWEEN '2024-01-01' AND '2024-12-31'
  AND status = 'completed'
ORDER BY total DESC
LIMIT 100;

-- Confronta con approcci diversi
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE status = 'completed'
  AND order_date >= '2024-01-01'
  AND order_date <= '2024-12-31'
ORDER BY total DESC
LIMIT 100;

Monitoraggio nel Tempo

Crea una tabella log prestazioni:

CREATE TABLE query_performance_log (
    log_id SERIAL PRIMARY KEY,
    query_hash TEXT,
    execution_time_ms INTEGER,
    row_count INTEGER,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    notes TEXT
);

-- Registra query lente
INSERT INTO query_performance_log
    (query_hash, execution_time_ms, row_count, notes)
SELECT
    md5(query),
    EXTRACT(MILLISECONDS FROM NOW() - query_start),
    result_rows,
    'Query lenta rilevata'
FROM pg_stat_activity
WHERE state = 'active'
  AND NOW() - query_start > INTERVAL '5 seconds';

Riepilogo Best Practice

Flusso di Lavoro Giornaliero

Inizia con EXPLAIN per nuove query complesse
Usa LIMIT quando esplori dati
Chiudi connessioni non utilizzate
Riavvia regolarmente HarborDB (settimanalmente)
Monitora risorse di sistema durante lavoro pesante

Manutenzione Settimanale

Rivedi log prestazioni query
Controlla indici non utilizzati
Aggiorna statistiche PostgreSQL (ANALYZE)
Pulisci file temporanei
Backup configurazioni prestazioni

Revisione Mensile

Analizza pattern query lente
Considera partizionamento tabelle per crescita
Rivedi necessità hardware
Aggiorna HarborDB e PostgreSQL
Documenta miglioramenti prestazioni

Guida all'Ottimizzazione delle Prestazioni