Benvenuti in HarborDB! Questa guida ti accompagnerà nella creazione della tua prima connessione PostgreSQL. Che tu stia connettendoti a un database locale sul tuo Mac o a un server remoto, HarborDB rende il processo semplice e sicuro.

Prerequisiti

Prima di iniziare, assicurati di avere:

HarborDB installato (vedi Guida all'Installazione)
Server PostgreSQL in esecuzione e accessibile
Dettagli della connessione pronti:
- Nome host o indirizzo IP
- Numero di porta (predefinito: 5432)
- Nome del database
- Nome utente e password
- Opzionale: certificato SSL se richiesto

Passo 1: Avvia HarborDB e Accedi alle Connessioni

Apri HarborDB dalla cartella Applicazioni o Launchpad
Individua la barra laterale Connessioni sul lato sinistro della finestra
Clicca il pulsante "+" o vai su File → Aggiungi Connessione

Passo 2: Compila i Dettagli della Connessione

La finestra di dialogo della connessione ha diversi campi da completare:

Informazioni Base

Nome: Un nome descrittivo per questa connessione (es. "Sviluppo Locale", "Server di Produzione")
Host: L'indirizzo del server PostgreSQL
- Database locale: localhost o 127.0.0.1
- Server remoto: Indirizzo IP o hostname (es. db.example.com)
Porta: Porta PostgreSQL (predefinito: 5432)
Database: Il database specifico a cui connettersi
Nome Utente: Il tuo nome utente PostgreSQL
Password: La tua password PostgreSQL

Opzioni Avanzate (Opzionali)

Schema: Schema preferito (predefinito: public)
Modalità SSL: Scegli in base alla configurazione del server:
- prefer: Usa SSL se disponibile
- require: Richiede connessione SSL
- verify-full: Richiede SSL con validazione del certificato
Timeout: Timeout della connessione in secondi
Nome Applicazione: Identificatore personalizzato per questa connessione

Passo 3: Testa la Tua Connessione

Prima di salvare, testa sempre la tua connessione:

Clicca "Test Connessione" nella finestra di dialogo
Attendi conferma - Dovresti vedere "Connessione riuscita"
Rivedi eventuali avvisi su SSL o altre impostazioni

Risultati Comuni del Test

✅ Successo: Sei pronto a salvare e connetterti
❌ Fallimento: Controlla il messaggio di errore per indizi:
- "Connessione rifiutata": Server non in esecuzione o firewall che blocca
- "Autenticazione fallita": Nome utente/password incorretti
- "Il database non esiste": Nome del database incorretto

Passo 4: Salva e Proteggi la Tua Connessione

Opzioni di Memorizzazione Password

HarborDB offre memorizzazione sicura delle password:

Salva in Keychain (Consigliato): Password crittografata nel macOS Keychain
Salva nella connessione: Password memorizzata con le impostazioni di connessione (meno sicuro)
Chiedi ogni volta: Richiede password ad ogni connessione

Scegliere l'Opzione Giusta

| Metodo Memorizzazione | Sicurezza | Convenienza | Ideale Per | | --------------------- | --------- | ----------- | ---------- | | macOS Keychain | 🔒 Alta | ⚡ Alta | Uso quotidiano, computer fidati | | File di connessione | 🔒 Media | ⚡ Alta | Setup rapido, test | | Chiedi ogni volta | 🔒 Massima | ⚡ Bassa | Computer condivisi, alta sicurezza |

Salvare la Tua Connessione

Scegli il metodo di memorizzazione password
Clicca "Salva" per memorizzare la connessione
Trova la tua connessione nella barra laterale Connessioni
Doppio-clicca per connetterti

Passo 5: Connettiti ed Esplora

Una volta connesso, puoi:

Navigare nel Tuo Database

Espandi la connessione per vedere i database
Esplora schemi e tabelle nella barra laterale
Clicca con il tasto destro su una tabella per azioni rapide:
- Visualizza struttura tabella
- Anteprima prime 100 righe
- Genera query SELECT

Azioni di Avvio Rapido

Apri Editor Query: Clicca l'icona SQL o premi ⌘ + N
Esegui una query di test:
```
SELECT version();
```
Esplora l'interfaccia: Familiarizza con schede, pannelli e strumenti

Gestione delle Connessioni

Organizzare Connessioni Multiple

Mentre aggiungi più connessioni, tienile organizzate:

Preferiti: Segnala le connessioni usate frequentemente per accesso rapido
Gruppi: Organizza per progetto, ambiente o team
Codifica colori: Usa tag o convenzioni di denominazione

Modificare Connessioni Esistenti

Clicca con il tasto destro sulla connessione nella barra laterale
Seleziona "Modifica Connessione"
Aggiorna eventuali campi se necessario
Testa e salva le modifiche

Duplicare Connessioni

Risparmia tempo duplicando connessioni simili:

Clicca con il tasto destro sulla connessione sorgente
Seleziona "Duplica"
Modifica solo i campi cambiati
Salva come nuova connessione

Best Practice di Sicurezza

Sicurezza Password

Non condividere mai password del Keychain
Usa password forti per utenti PostgreSQL
Ruota password periodicamente
Evita di riutilizzare password su server diversi

Sicurezza Connessioni

Usa SSL per connessioni remote
Limita i permessi del database alle operazioni necessarie
Usa connessioni in sola lettura per reporting
Verifica regolarmente i log di connessione

Sicurezza di Rete

Configurazione firewall: Permetti solo IP fidati
Accesso VPN per database remoti
Tunnel SSH per ulteriori livelli di sicurezza

Scenari Comuni di Connessione

PostgreSQL Locale (Installato via Homebrew)

Nome: PostgreSQL Locale
Host: localhost
Porta: 5432
Database: postgres
Nome Utente: tuo_nome_utente
Password: [Keychain]

Contenitore Docker PostgreSQL

Nome: Docker Dev DB
Host: localhost
Porta: 5432  # O porta personalizzata se mappata diversamente
Database: app_database
Nome Utente: postgres
Password: postgres_password

Amazon RDS PostgreSQL

Nome: AWS Produzione
Host: your-db-instance.region.rds.amazonaws.com
Porta: 5432
Database: production_db
Nome Utente: app_user
Modalità SSL: verify-full

Google Cloud SQL

Nome: GCP Cloud SQL
Host: /cloudsql/project:region:instance
Porta: 5432
Database: cloud_db
Modalità SSL: require

Risoluzione Problemi di Connessione

"Impossibile Connettersi al Server"

Verifica che PostgreSQL sia in esecuzione:

# In Terminale
pg_isready -h localhost -p 5432

Controlla le impostazioni del firewall:
- Firewall macOS (Preferenze di Sistema → Sicurezza & Privacy)
- Regole firewall di rete

Testa la connettività di rete:

# In Terminale
ping your-server-address
telnet your-server-address 5432

"Autenticazione Password Fallita"

Controlla il metodo di autenticazione PostgreSQL:
- Visualizza file pg_hba.conf
- Assicurati autenticazione md5 o scram-sha-256

Reimposta la password se necessario:

ALTER USER username WITH PASSWORD 'new_password';

Verifica che l'utente abbia accesso al database:

-- Connettiti come superuser
\du  -- Elenca utenti
\l   -- Elenca database

Errori di Connessione SSL/TLS

Controlla i requisiti SSL:
- Il server potrebbe richiedere modalità SSL specifica
- Il certificato potrebbe dover essere importato
Regola la modalità SSL nelle impostazioni di connessione
Importa certificato se usi modalità verify-full

Suggerimenti sulle Prestazioni

Pool di Connessioni

Mantieni connessioni aperte per uso frequente
Chiudi connessioni non usate per liberare risorse
Usa pooling di connessioni per applicazioni

Ottimizzazione di Rete

Connessioni locali: Usa localhost per le migliori prestazioni
Connessioni remote: Assicurati larghezza di banda sufficiente
Compressione: Abilita se lavori con set di risultati grandi

Prossimi Passi

Ora che sei connesso:

Esplora le Basi delle Query - Impara a scrivere ed eseguire query SQL
Navigazione Database - Esplora schemi, tabelle e relazioni
Esportazione Dati - Salva risultati in CSV o JSON

Ottenere Aiuto

Se hai ancora problemi:

Controlla la nostra Guida al Supporto per ulteriore risoluzione problemi
Visita le FAQ per domande comuni
Contatta il Supporto per assistenza personalizzata

Creare la Prima Connessione