HarborDB

Problemi Comuni & Risoluzione

Support
•Ultimo aggiornamento: 16 febbraio 2026

Benvenuti alla guida di risoluzione problemi di HarborDB. Questa risorsa completa ti aiuta a identificare rapidamente e risolvere i problemi più comuni incontrati mentre lavori con HarborDB e PostgreSQL. Che tu stia riscontrando problemi di connessione, prestazioni lente o problemi dell'interfaccia, qui troverai soluzioni passo-passo.

Come Usare Questa Guida

  1. Identifica il tuo problema dalle categorie sotto
  2. Segui i passi di risoluzione problemi in ordine
  3. Prova le soluzioni finché il problema non è risolto
  4. Se ancora non risolto, usa la sezione "Contattare il Supporto"

Riferimento Rapido: Problemi Comuni

| Problema | Causa Probabile | Soluzione Rapida | | ------------------------------ | ---------------------------------------- | ------------------------------------------- | | Non riesco a connettermi a PostgreSQL | Server non in esecuzione, firewall blocca | Avvia PostgreSQL, controlla impostazioni firewall | | Prestazioni query lente | Indici mancanti, dataset grandi | Aggiungi indici, usa LIMIT, ottimizza query | | Uso memoria elevato | Troppe schede aperte, set risultati grandi | Chiudi schede non usate, abilita modalità streaming | | Esportazione fallisce | Problemi di permessi, disco pieno | Controlla permessi file, libera spazio disco | | Interfaccia sembra lenta | Vincoli di risorse di sistema | Chiudi altre app, riavvia HarborDB |

Problemi di Connessione

"Impossibile connettersi al server PostgreSQL"

Sintomi:

  • Errori di timeout di connessione
  • Messaggi "Connessione rifiutata"
  • Caricamento infinito quando si testa la connessione

Risoluzione Passo-Passo:

  1. Controlla Stato Server PostgreSQL:

    # In Terminale, controlla se PostgreSQL è in esecuzione
pg_isready -h localhost -p 5432
    • Se non in esecuzione: brew services start postgresql (Homebrew) o avvia tramite Preferenze di Sistema

  2. Verifica Dettagli Connessione:

    • Hostname: localhost per locale, IP/hostname corretto per remoto
    • Porta: Default è 5432, conferma la tua porta PostgreSQL
    • Nome database: Deve esistere prima della connessione
    • Nome utente/password: Sensibili a maiuscole/minuscole, controlla credenziali

  3. Controlla Impostazioni Firewall:

    • Preferenze di Sistema → Sicurezza & Privacy → Firewall
    • Assicurati che la porta PostgreSQL (5432) sia permessa
    • Prova a disabilitare temporaneamente il firewall per test

  4. Testa Connettività di Rete:

    # Per server remoti
ping tuo-indirizzo-server
telnet tuo-indirizzo-server 5432

Soluzioni Comuni:

  • ✅ Avvia servizio PostgreSQL
  • ✅ Corretto hostname/indirizzo IP
  • ✅ Apri porta firewall 5432
  • ✅ Usa credenziali corrette

"Autenticazione password fallita"

Cause:

  • Nome utente o password incorretti
  • Mismatch metodo di autenticazione PostgreSQL
  • Utente senza permessi sul database

Soluzioni:

  1. Reimposta Password PostgreSQL:

    -- Connettiti come superuser (tramite riga di comando)
ALTER USER username WITH PASSWORD 'nuova_password';

  2. Controlla Metodo di Autenticazione:

    • Visualizza file pg_hba.conf
    • Metodi comuni: md5, scram-sha-256, trust
    • Aggiorna metodo se necessario, riavvia PostgreSQL

  3. Verifica Permessi Utente:

    -- Elenca utenti e permessi
\du

-- Elenca database e accessi
\l

Errori di Connessione SSL/TLS

Quando ci si connette a server remoti:

  1. Controlla Requisiti SSL:

    • Il server potrebbe richiedere modalità SSL specifica
    • Potrebbe necessitare importazione certificato

  2. Prova Diverse Modalità SSL in HarborDB:

    • Inizia con prefer
    • Poi prova require
    • Infine verify-full (richiede certificato)

  3. Importa Certificati se usi verify-full:

    • Ottieni certificato dall'amministratore del server
    • Importa in Accesso Keychain macOS
    • Concedi accesso a HarborDB al certificato

Problemi di Prestazioni

Esecuzione Query Lenta

Passi di Diagnosi:

  1. Usa EXPLAIN per Analizzare:

    • Clicca pulsante "Spiega" (⚡) in HarborDB
    • Cerca "Seq Scan" (scansione completa tabella) - spesso lento
    • Cerca "Index Scan" - di solito più veloce

  2. Controlla Indici Mancanti:

    -- Trova colonne filtrate frequentemente senza indici
SELECT schemaname, tablename, attname
FROM pg_stats
WHERE schemaname NOT LIKE 'pg_%'
  AND n_distinct > 100
  AND attname NOT IN (
    SELECT column_name
    FROM information_schema.columns
    WHERE table_schema = schemaname
      AND table_name = tablename
  );

  3. Aggiungi Indici Appropriati:

    -- Indice a colonna singola
CREATE INDEX idx_tabella_colonna ON nome_tabella(nome_colonna);

-- Indice multi-colonna per pattern query comuni
CREATE INDEX idx_tabella_col1_col2 ON nome_tabella(col1, col2);

Fix Prestazioni Rapidi:

  • Aggiungi clausola LIMIT a query esplorative
  • Seleziona solo colonne necessarie (non SELECT *)
  • Usa clausole WHERE con colonne indicizzate
  • Evita funzioni nelle clausole WHERE che impediscono uso indice

Uso Memoria Elevato

Sintomi:

  • HarborDB usa RAM eccessiva (controlla Activity Monitor)
  • Il sistema diventa lento
  • Errori "Memoria esaurita"

Soluzioni:

  1. Riduci Dimensione Cache Query:

    • Preferenze → Prestazioni → Cache Query
    • Riduci da default 256MB a 128MB se memoria limitata

  2. Abilita Modalità Streaming:

    • Preferenze → Prestazioni → Risultati Streaming
    • Abilita per risultati > 10.000 righe
    • Riduce uso memoria per dataset grandi

  3. Gestisci Schede Aperte:

    • Chiudi schede query non utilizzate
    • HarborDB mantiene set risultati in memoria per scheda
    • Lavoro regolare: massimo 5-10 schede

  4. Riavvia HarborDB:

    • Esci e riavvia giornalmente durante uso intenso
    • Pulisce uso memoria accumulato

L'Applicazione Sembra Lenta

Fix Rapidi:

  1. Chiudi Altre Applicazioni:

    • Specialmente app intensive di risorse (Chrome con molte schede, Docker, ecc.)
    • Controlla Activity Monitor per pressione memoria

  2. Riduci Animazioni UI:

    • Preferenze → Aspetto → Disabilita animazioni
    • Esperienza più fluida su hardware vecchio

  3. Semplifica Interfaccia:

    • Comprimi sezioni barra laterale non in uso
    • Usa tema colore più semplice
    • Disabilita evidenziazione sintassi per query molto grandi

Problemi di Esportazione e File

Esportazione Fallisce o Crea File Vuoti

Cause Comuni e Soluzioni:

  1. Problemi di Permessi:

    # Controlla permessi cartella
ls -la ~/Desktop/

# Prova diversa posizione salvataggio
# Usa cartella Documenti invece di Desktop

  2. Problemi Spazio Disco:

    # Controlla spazio disco disponibile
df -h

# Necessari almeno 2x dimensione esportazione liberi

  3. Problemi Formato File:

    • CSV: Prova delimitatore diverso (virgola, punto e virgola, tabulazione)
    • CSV: Aggiungi qualificatori testo (virgolette attorno ai campi)
    • JSON: Prova entrambi i formati "Leggibile" e "Compatto"

  4. Ottimizzazione Esportazione Grandi:

    • Esporta in chunk più piccoli
    • Usa CSV invece di JSON per dataset grandi
    • Abilita compressione nelle impostazioni di esportazione

"File Non Trovato" o Esportazioni Mancanti

  1. Controlla Posizione Salvataggio Predefinita:

    • Preferenze → Esporta → Posizione Salvataggio Predefinita
    • Cambia a cartella a cui accedi frequentemente

  2. Cerca File:

    # Cerca file CSV/JSON recenti
find ~ -name "*.csv" -mtime -1
find ~ -name "*.json" -mtime -1

  3. Controlla Cestino:

    • Le esportazioni potrebbero essere state accidentalmente eliminate
    • Ripristina dal Cestino se trovate

Problemi di Interfaccia e Visualizzazione

Tema Non Si Applica Correttamente

Problemi Modalità Scura/Chiara macOS:

  1. Controlla Impostazioni Sistema:

    • Impostazioni Sistema → Aspetto
    • Assicurati "Auto" o tema desiderato selezionato

  2. Riavvia HarborDB:

    • Esci completamente (⌘ + Q)
    • Riapri per applicare tema di sistema

  3. Forza Tema in HarborDB:

    • Preferenze → Aspetto → Tema
    • Scegli "Chiaro", "Scuro", o "Sistema"

Funzionalità o Menu Mancanti

  1. Aggiorna HarborDB:

    • Controlla aggiornamenti (HarborDB → Controlla Aggiornamenti)
    • App Store → Scheda Aggiornamenti

  2. Ripristina Layout Interfaccia:

    • Finestra → Ripristina Layout
    • Ripristina disposizione pannelli predefinita

  3. Controlla Disponibilità Funzionalità:

    • Alcune funzionalità richiedono specifiche versioni PostgreSQL
    • Verifica compatibilità nella documentazione della funzionalità

Problemi di Visualizzazione Testo

Problemi Dimensione Font/Legibilità:

  1. Regola Dimensione Font Editor:

    • Preferenze → Editor → Dimensione Font
    • Aumenta per migliore leggibilità

  2. Usa Zoom macOS:

    • Impostazioni Sistema → Accessibilità → Zoom
    • Abilita per ingrandimento temporaneo

  3. Modalità Alto Contrasto:

    • Impostazioni Sistema → Accessibilità → Schermo
    • Aumenta contrasto per migliore visibilità

Problemi Specifici macOS

Errore "App è Danneggiata"

Quando si apre HarborDB:

# Rimuovi attributo quarantine
sudo xattr -cr /Applications/HarborDB.app

# Riapri HarborDB
open /Applications/HarborDB.app

Avvisi Gatekeeper

Per download diretti (non App Store):

  1. Impostazioni Sistema → Privacy & Sicurezza
  2. Scorri a sezione "Sicurezza"
  3. Clicca "Apri Comunque" accanto all'avviso HarborDB
  4. Conferma apertura

Problemi Touch ID/Accesso Keychain

Errori "HarborDB vuole usare la tua password":

  1. Ripristina Permessi Keychain:

    • Apri app Accesso Keychain
    • Cerca "HarborDB"
    • Elimina voci esistenti
    • Riaggiungi connessione in HarborDB

  2. Ripara Keychain:

    • Accesso Keychain → File → Keychain First Aid
    • Esegui riparazione su keychain "Login"

Compatibilità con Versioni macOS

Minimo: macOS 12.0 (Monterey) Raccomandato: macOS 13.0 (Ventura) o successivo

Controlla Compatibilità:

# Controlla versione macOS
sw_vers

# Controlla architettura (Apple Silicon vs Intel)
uname -m

Problemi Specifici del Database

"La relazione non esiste"

Quando si interrogano tabelle:

  1. Controlla Schema:

    -- Elenca tutte le tabelle nello schema corrente
\dt

-- Elenca tabelle in tutti gli schemi
SELECT schemaname, tablename
FROM pg_tables
WHERE tablename LIKE '%tua_tabella%';

  2. Usa Nomi Qualificati:

    -- Invece di: SELECT * FROM utenti;
-- Usa qualificazione schema:
SELECT * FROM public.utenti;
SELECT * FROM auth.utenti;

  3. Imposta Schema Predefinito:

    • Modifica connessione in HarborDB
    • Imposta "Schema Predefinito" a schema comunemente usato

Errori di Permesso sugli Oggetti del Database

Permesso negato per relazione

  1. Controlla i Tuoi Permessi:

    -- Connettiti come superuser o proprietario della tabella
SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_name = 'tua_tabella';

  2. Richiedi Permessi:

    -- Esempio: Concedi permesso SELECT
GRANT SELECT ON nome_tabella TO tuo_nome_utente;

Gestione Dataset Grandi

"Memoria esaurita" o estremamente lento:

  1. Usa Paginazione Lato Server:

    -- Invece di: SELECT * FROM tabella_gigante;
-- Usa:
SELECT * FROM tabella_gigante LIMIT 1000 OFFSET 0;
-- Poi incrementa OFFSET per pagine successive

  2. Abilita Streaming in HarborDB:

    • Preferenze → Prestazioni → Modalità Streaming
    • Imposta soglia (es., 10.000 righe)

  3. Usa Viste Materializzate per query complesse frequenti

Problemi di Rete e Connessione Remota

Connessioni Remote Lente

Consigli di Ottimizzazione:

  1. Abilita Compressione:

    • Impostazioni connessione → Avanzate → Compressione
    • Riduce dimensione trasferimento dati

  2. Usa Tunnel SSH:

    • Più sicuro della connessione diretta
    • Può migliorare le prestazioni su reti ristrette

  3. Pianifica Query Pesanti:

    • Esegui durante ore di minor traffico
    • Usa funzionalità pianificatore query di HarborDB

Cadute Connessione Intermittenti

  1. Aumenta Impostazioni Timeout:

    • Impostazioni connessione → Timeout
    • Aumenta da 30 a 60 secondi

  2. Abilita Keep-Alive:

    • Impostazioni connessione → Keep-Alive
    • Mantiene connessioni inattive

  3. Controlla Stabilità Rete:

    # Testa stabilità rete
ping -c 100 tuo-indirizzo-server
# Cerca perdita pacchetti

Prima di Contattare il Supporto

Informazioni da Raccogliere

Se i problemi persistono dopo la risoluzione problemi, raccogli queste informazioni:

  1. Informazioni di Sistema:

    • Versione macOS (Menu Apple → Informazioni su Questo Mac)
    • Versione HarborDB (HarborDB → Informazioni su HarborDB)
    • Versione PostgreSQL (SELECT version();)

  2. Dettagli Errore:

    • Messaggio di errore esatto (screenshot se possibile)
    • Passi per riprodurre il problema
    • Quando il problema è iniziato

  3. Dettagli di Configurazione:

    • Impostazioni connessione (senza password)
    • Query che causa problemi (se applicabile)
    • Impostazioni di esportazione (se relativo all'esportazione)

Strumenti Diagnostici in HarborDB

  1. Genera Report Diagnostico:

    • Aiuto → Crea Report Diagnostico
    • Include log, configurazione, informazioni di sistema

  2. Visualizza Log Applicazione:

    • Aiuto → Mostra Log
    • Filtra per messaggi di errore e avviso

  3. Console.app per Log di Sistema:

    • Apri Console.app
    • Cerca "HarborDB"
    • Cerca report di crash

Auto-Controllo Rapido

Prima di contattare il supporto, verifica:

  • [ ] macOS è aggiornato
  • [ ] HarborDB è l'ultima versione
  • [ ] Il server PostgreSQL è in esecuzione
  • [ ] La connessione di rete è stabile
  • [ ] Spazio disco sufficiente disponibile
  • [ ] L'utente ha i permessi necessari

Contattare il Supporto

Se hai provato tutti i passi di risoluzione problemi e il problema persiste:

  1. Email Supporto: support@harbordb.com

  2. Includi nella tua email:

    • Report diagnostico (dal menu Aiuto)
    • Screenshot dei messaggi di errore
    • Passi per riprodurre il problema
    • Quali passi di risoluzione problemi hai provato

  3. Tempo di Risposta Atteso:

    • Risposta iniziale: Entro 24-48 ore
    • Orari lavorativi: Lunedi-Venerdì, 9AM-5PM EST
    • Problemi di emergenza: Contrassegna email come "URGENTE"

Misure Preventive

Manutenzione Regolare

Settimanale:

  • Riavvia HarborDB per pulire la memoria
  • Pulisci file temporanei di esportazione
  • Backup impostazioni connessione importanti

Mensile:

  • Aggiorna HarborDB e PostgreSQL
  • Rivedi e ottimizza query lente
  • Pulisci connessioni non utilizzate

Best Practice per Evitare Problemi

  1. Gestione Connessioni:

    • Usa nomi di connessione significativi
    • Testa regolarmente le connessioni
    • Rimuovi connessioni non utilizzate

  2. Sviluppo Query:

    • Usa sempre LIMIT durante l'esplorazione
    • Testa con EXPLAIN prima di eseguire query grandi
    • Salva query complesse per riutilizzo

  3. Manutenzione Sistema:

    • Tieni macOS aggiornato
    • Backup Time Machine regolari
    • Monitora spazio disco

Risorse Aggiuntive

Torna alla categoriaTorna alla Documentazione

È stato utile?

Aiutaci a migliorare questa documentazione fornendo feedback.

Segnala ProblemaContatta il SupportoEdit this page