Primi passi

Panoramica dell'applicazione e del suo flusso di lavoro.

Calíope è un client nativo per MySQL, MariaDB, Amazon Aurora e PostgreSQL disponibile su macOS, iPad e iPhone. Il flusso di lavoro principale ha due schermate: la Gestione delle connessioni, dove si amministrano i profili di server, e il workspace, che si apre una volta stabilita la connessione.

Il workspace contiene una barra laterale con l'albero degli schemi, una barra di tab per aprire più strumenti simultaneamente e una barra di accesso rapido a tutti gli strumenti.

Parole chiave: inizio, overview, presentazione, cos'è, introduzione

Un solo file avvia dodici server di prova sul tuo Mac, già popolati.

Se non hai nessun server a portata di mano, o vuoi vedere di cosa è capace Calíope prima di puntarlo su uno tuo, puoi avviare sul tuo Mac lo stesso ambiente di prova su cui l'app viene sviluppata. È un solo file e non richiede altro che Docker.

→ Scarica caliope-testbed.command

Cosa serve. macOS 12 o successivo, Docker Desktop — gratuito per uso personale, su docker.com — e circa 2 GB liberi di disco e di memoria.

Come si avvia. La via più pulita è incollare queste quattro righe nel Terminale:

cd ~/Downloads
curl -fLO https://caliope.org/caliope-testbed.command
chmod +x caliope-testbed.command
./caliope-testbed.command

Se preferisci scaricarlo dal browser servono due cose in più, e in questo ordine: renderlo eseguibile (chmod +x sul file scaricato) e aprirlo la prima volta con clic destro › Apri invece del doppio clic, perché macOS mette in quarantena tutto ciò che scarica un browser. Con curl non serve nessuna delle due.

La prima volta ci vogliono alcuni minuti per scaricare le immagini, e mentre lavora dice a che punto è. Alla fine stampa un unico resoconto con gli indirizzi, le porte e le credenziali.

Cosa avvia. Dodici server, scelti perché nessuno strumento di Calíope resti senza niente da mostrare:

Con un bastione SSH e generatori di carico continui: così il Pannello, il registro delle query lente, l'elenco dei processi e il monitor di replica hanno traffico vero da mostrare.

I profili non si scrivono a mano. Ogni esecuzione lascia un file caliope-testbed-connections.json accanto al lanciatore, con i dodici nodi come un unico gruppo. In Calíope: Impostazioni › Connessioni › Importa. L'importazione unisce: non viene rimosso niente di quello che hai già. L'utente è caliope e la password caliopepass. I due profili via tunnel chiedono la loro password SSH (tunnel123) la prima volta, perché i segreti SSH vivono solo nel Portachiavi.

Anche da iPad e iPhone. Ogni profilo porta l'indirizzo di rete del Mac come alternativa, quindi lo stesso file funziona su tutti e tre i dispositivi senza modificare niente — con il Mac accesso, il banco di prova in funzione e entrambi sulla stessa rete.

I quattro comandi.

Attenzione a --fresh: è distruttivo e va oltre Calíope. Ferma tutti i container Docker del tuo Mac e cancella immagini, volumi e cache che nessuno sta usando, compresi quelli dei tuoi altri progetti. Lo dice e chiede conferma prima di toccare qualsiasi cosa. In cambio è l'unica esecuzione che offre di scaricare i tre insiemi di dati di esempio, uno per motore: Sakila per MySQL e MariaDB, Pagila per PostgreSQL e il campione Atlas per MongoDB. Ognuno viene chiesto a parte.

Questo non è un server su cui lavorare. Le password sono pubbliche e scritte dentro il file stesso, niente è cifrato e tutto ascolta sulla tua macchina. È un banco di prova: per imparare, per provare uno strumento prima di usarlo sui tuoi dati, e perché una segnalazione di errore si possa riprodurre.

Parole chiave: docker, prova, banco di prova, esempio, senza server, demo, esercitarsi, sakila

Crea un profilo e stabilisci la tua prima connessione a un server.

Dove si trova: Gestione delle connessioni › Pulsante +

Nella Gestione delle connessioni premi il pulsante + nella barra laterale per creare un nuovo profilo. Compila l'host, la porta (3306 per impostazione predefinita), l'utente e la password. Premi Testa la connessione per verificare i dati prima di salvare.

Una volta validati, premi Connetti per aprire il workspace. Il profilo viene salvato e sarà disponibile nell'elenco per le connessioni future.

Parole chiave: prima volta, nuova connessione, profilo, host, porta

Come usare la barra laterale Strumenti, le schede, il selettore di server e la barra di stato.

Lo Spazio di lavoro ha tre zone: la barra laterale Strumenti a sinistra, la barra delle schede con gli strumenti aperti e la barra di stato in basso.

Per aprire uno strumento premi la sua riga nella barra laterale. Ognuno si apre in una scheda propria; puoi tenerne aperte diverse e spostarti tra loro con ⌘] e ⌘[. Le righe sono raggruppate per tema, e sia l'ordine sia i gruppi si regolano dal pulsante ⋮≡ della barra laterale stessa (vedi Personalizzare la barra principale). Ogni gruppo si comprime premendo la sua intestazione, e il campo in alto nella barra laterale filtra gli strumenti per nome (vedi Filtrare e comprimere la barra laterale).

Selettore di server: il menu con il nome del server attivo sta in alto a sinistra (macOS) o a sinistra della barra delle schede (iPad). Da lì puoi cambiare sessione, aggiungere un altro server o disconnetterti. Calíope consente più connessioni attive insieme.

Nascondere la barra laterale: il pulsante della barra del titolo la richiude e lascia tutta la larghezza allo strumento attivo.

L'albero dello schema non è qui: vive dentro l'Editor SQL, l'unico posto in cui serve.

Senza connessione: lo Spazio di lavoro senza server mostra una striscia di accesso rapido con ciò che non richiede connessione — Editor SQL, Snippet, Editor SQLite, Anteprima file, Errori e Report. Il chevron alla sua estremità destra la richiude.

Su iPhone e in finestra stretta: gli strumenti stanno in una barra inferiore con i primi quattro del tuo ordine e un pulsante Altro per il resto. Quali siano quei quattro lo decidi tu riordinando la barra laterale.

Parole chiave: spazio di lavoro, workspace, barra laterale, strumenti, schede, navigazione, selettore di server, barra di stato, offline

L'elenco del navigatore lo decide la connessione, non un'impostazione che hai cambiato.

Il navigatore degli strumenti non mostra sempre lo stesso elenco: mostra ciò che questa sessione sa fare. Alla connessione Calíope stabilisce di cosa è capace quella connessione e nasconde il resto. Ciò che non vedi non è rotto né disattivato: non viene offerto.

Nasconderlo è voluto. Uno strumento che si apre solo per dire «qui no» ti ha già fatto perdere il viaggio, e una riga spenta invita a cercare l'interruttore che la accenda — e non esiste.

Per il tipo di database. Un server relazionale e uno a documenti non si somigliano: in una sessione a documenti non c'è editor SQL né diagramma entità-relazione, e in una relazionale non c'è esploratore di collezioni. Questo non cambia mai, e non è una mancanza di nessuno dei due.

Per ciò che quella connessione sa fare. Nemmeno due server relazionali offrono esattamente le stesse cose. A volte il motore non ha quel concetto, e allora lo strumento non comparirà mai su quel server perché non ci sarebbe nulla da mostrare; a volte Calíope non l'ha ancora scritto per quel motore, e comparirà in una versione successiva. Le due assenze si somigliano di proposito: quello che ti serve sapere adesso è se lo strumento serve, non perché no.

Senza connessione il navigatore mostra solo ciò che funziona senza server: l'Editor SQL, gli Snippet, l'Editor SQLite, l'Anteprima file, gli Errori e i Report — questi ultimi a metà, perché senza server si possono vedere, modificare ed esportare, ma non eseguire.

Dove altro si nota. Il pulsante Vai di questa guida può puntare a uno strumento che la tua sessione non offre: allora non si apre nulla e la barra di stato lo dice, col suo nome. È una risposta, non un guasto.

E questa guida li contiene tutti. L'indice non cambia con il server a cui sei connesso, quindi qui troverai argomenti di strumenti che la tua sessione attuale non mostra. Se te ne manca uno, prova ad aprire una sessione verso un altro server: l'elenco viene ricalcolato a ogni connessione.

Parole chiave: strumenti, mancanti, non visibili, navigatore, disponibilità, motore, sessione, nascosti, Vai

Comprimi i gruppi che non usi e scrivi nel campo in alto per trovare uno strumento dal nome.

La barra laterale Strumenti distribuisce per temi la ventina di strumenti di Calíope. Due cose la accorciano.

Comprimere un gruppo: premi la sua intestazione. Il chevron ruota e le righe del gruppo spariscono; accanto al nome resta il numero di strumenti che sta nascondendo, così nessuno si perde senza lasciare traccia. Premila di nuovo per riaprirlo. Ciò che comprimi viene ricordato alla chiusura dell'app e viaggia verso l'altro Mac, iPad o iPhone se hai attiva la sincronizzazione con iCloud.

Filtrare: il campo in alto lascia solo gli strumenti che corrispondono a quello che scrivi. Cerca nel nome dello strumento, nel suo nome completo del catalogo e nella frase che dice cosa fa, e inoltre nel nome del suo gruppo — così scrivere il nome di un gruppo lo mostra per intero. Gli accenti non contano: replicacion trova Replicación.

Mentre filtri, ogni gruppo con corrispondenze viene disegnato aperto, anche quelli che avevi compressi. Niente di ciò che trovi può restare nascosto dentro un gruppo chiuso. I tuoi gruppi compressi non vengono toccati: svuota il campo e tutto torna esattamente com'era.

Premi Esc o la × per svuotare il campo. Il filtro non viene ricordato alla chiusura dell'app: una barra laterale che parte mezza vuota per un motivo che non ricordi è peggio che riscrivere tre lettere.

Parole chiave: barra laterale, strumenti, filtrare, cercare, gruppi, comprimere, espandere

Cosa funziona senza connettersi ad alcun server, e cosa no.

Calíope include un workspace offline accessibile anche quando non c'è alcun server connesso. È utile per redigere query e organizzare i tuoi snippet senza bisogno di connessione.

Come accedere:

Dalla Gestione delle connessioni, senza connettersi ad alcun server. Dove sta il pulsante dipende dallo spazio: su schermo largo — il Mac e l'iPad — è nella schermata di benvenuto, accanto a «Crea profilo»; su schermo stretto — l'iPhone, e l'iPad a finestra divisa — quella schermata non viene disegnata, quindi sta nella barra in basso, con l'icona del terminale.

Strumenti disponibili in modalità offline:
- Editor SQL — scrivi e salva SQL, usa la cronologia e gli snippet. Le query non possono essere eseguite su un server.
- Snippet — crea, modifica e copia i tuoi snippet di codice.
- Editor SQLite — apri un file .sqlite dal disco e lavoraci per intero: non serve un server, perché il file è il database.
- Anteprima file — guarda CSV, JSON, Markdown e il resto senza uscire dall'app.
- Errori — il registro è locale, e devi poterlo leggere proprio quando non riesci a connetterti.
- Report — puoi vedere, modificare ed esportare i risultati che avevi già; eseguirne uno richiede un server, e la vista lo dice.

Banner di modalità offline: una striscia dorata nella parte superiore del workspace indica che sei in modalità offline.

Per connetterti a un server dal workspace offline, premi il pulsante Connetti al server nella barra degli strumenti o nel banner superiore. Si apre la Gestione delle connessioni come pannello fluttuante senza perdere il contenuto dell'editor.

Parole chiave: offline, senza connessione, modalità offline, senza server, editor offline, workspace offline, editor senza connessione, snippet

Mostra il risultato, il tempo e l'avanzamento delle operazioni in corso.

La barra di stato appare nella parte inferiore del workspace e dell'editor SQL. Riflette lo stato dell'ultima operazione eseguita.

Informazioni che mostra:
- Messaggio di risultato — testo descrittivo dell'ultima operazione (righe interessate, tempo di esecuzione, errore).
- Avanzamento — barra di avanzamento o animazione di caricamento mentre una query o attività è in esecuzione.
- Percentuale — nelle operazioni lunghe (come backup o ripristini) mostra l'avanzamento numerico.

Copiare il messaggio:

macOS: fai doppio clic sull'area di testo della barra di stato per copiare il messaggio completo negli appunti. Utile per copiare messaggi di errore senza doverli selezionare manualmente.

iPad: lo stesso gesto di doppio tap copia il messaggio.

La barra di stato è sempre visibile e non può essere nascosta.

Parole chiave: barra di stato, status bar, avanzamento, messaggio, copiare messaggio, errore, tempo di esecuzione, doppio clic

Riordina e nascondi i pulsanti della barra dell'editor e di quella dei risultati.

Dove si trova: Editor SQL › Personalizza la barra

L'Editor SQL ha due barre di pulsanti proprie, personalizzabili separatamente:

- Barra dell'editor — sopra l'area di testo: esegui, formatta, commenta, cronologia, pannello dello schema…
- Barra dei risultati — sopra la griglia: esporta, grafico, profilatore di colonne, filtri…

Aprire il personalizzatore
Premi il pulsante ⋮≡ (icona slider.horizontal.3) all'inizio della barra da regolare.

Cosa puoi fare
- Riordinare — trascina ogni pulsante dove preferisci.
- Nascondere — deseleziona quelli che non usi; le loro azioni restano disponibili da menu e scorciatoie da tastiera.
- Ripristinare — riporta quella barra alla disposizione originale.

Entrambe le barre scorrono in orizzontale, così nessun pulsante resta irraggiungibile per quanto stretta sia la finestra.

Per il lanciatore di strumenti dello Spazio di lavoro vedi Personalizzare la barra principale.

Parole chiave: barra dell'editor, barra dei risultati, personalizzare, riordinare, nascondere, trascinare, editor sql

Riordina i pulsanti della barra principale del workspace per mettere prima i tuoi strumenti preferiti.

Dove si trova: Workspace › Personalizza la barra principale

La barra laterale di navigazione (launcher di applicazioni) organizza le scorciatoie a tutti gli strumenti del workspace in gruppi logici, per un flusso di lavoro ottimizzato:

1. Sviluppo e query — Editor SQL, Costruttore di query, Snippet, Log SQL ed Editor SQLite.
2. Progettazione e struttura — Cataloghi, Diagramma ER, Diff di schemi e Migrazione di oggetti.
3. Diagnostica e prestazioni — Dashboard, Salute del server, Avvisi SQL, Monitoraggio della replica e Visualizzatore di binlog.
4. Amministrazione del server — Info del server, Processi, Utenti, Backup e Manutenzione.
5. Assistente intelligente — Assistente IA.

Come aprire il personalizzatore
- In cima alla barra laterale di navigazione trovi il pulsante di personalizzazione ⋮≡ (icona slider.horizontal.3).
- Premilo per aprire la schermata di personalizzazione.

Cosa puoi fare
Il personalizzatore offre un controllo gerarchico e completamente dinamico, diviso in due schede:
- Scheda "Riordina gruppi" — trascina intere sezioni per cambiare l'ordine delle categorie, rinominarle o aggiungere gruppi personalizzati.
- Scheda "Riordina elementi" — trascina i singoli strumenti dentro ogni gruppo, oppure premi Sposta in... per spostare dinamicamente qualsiasi strumento in un'altra sezione.
- Ripristina — il pulsante Ripristina riporta ai gruppi e all'ordine nativi predefiniti con un solo tocco.

Persistenza e autoriparazione
La tua configurazione viene salvata in modo sicuro in UserDefaults (con la chiave caliope_sidebar_config_macos o caliope_sidebar_config_ipad). Se Calíope aggiunge un nuovo strumento in un aggiornamento futuro, verrà inserito automaticamente nel suo gruppo predefinito senza interferire con la personalizzazione già fatta.

Parole chiave: barra principale, quick access, nav strip, personalizzare, riordinare, pulsanti, trascinare, overflow

Lavora con più server MySQL, MariaDB, Aurora o PostgreSQL allo stesso tempo senza perdere il contesto di ciascuno.

Dove si trova: Server › Aggiungi sessione…

Calíope mantiene sessioni indipendenti per ciascun profilo di connessione che apri. Ogni sessione ha i propri tab, il proprio database attivo, la propria cronologia di query e le proprie preferenze di layout.

Aprire una nuova sessione
- macOS: menu Server › Aggiungi sessione… o scorciatoia ⌘⌥N. Puoi anche premere Nuova sessione dal selettore di server nell'angolo in alto a sinistra.
- iPad: apri il selettore di server (icona a sinistra della barra dei tab) e premi Aggiungi sessione.

Passare da una sessione all'altra
- Usa il selettore di server dall'angolo in alto a sinistra (macOS) o dalla barra dei tab (iPad). Ogni sessione mostra il nome del profilo, l'host e un punto colorato che indica il suo stato.
- macOS: scorciatoia ⌘⌥1…9 per saltare direttamente alle prime nove sessioni.

Stato per sessione
- Ogni sessione ricorda il database attivo, i tab aperti e la cronologia di query all'interno di QueryLogger.
- Le connessioni SSH e SSL si stabiliscono una sola volta per sessione; cambiando sessione non si riconnette.
- Il widget ancorato segue il profilo contrassegnato come ancorato in Preferenze › Widget, indipendentemente da quale sessione sia in primo piano.

Chiudere una sessione
- Chiudi tutti i tab con la × o usa Server › Disconnetti. Calíope chiude il tunnel SSH se esiste.
- Le password restano nel Keychain; non vengono richieste di nuovo alla riconnessione a meno che il profilo non richieda la biometria.

Parole chiave: sessioni, multi-sessione, più server, simultanee, cambiare sessione, selettore server, aggiungere sessione, session manager, ⌘⌥N, disconnettere

Come accedere all'indice completo dell'aiuto da ciascuna piattaforma.

Dove si trova: Aiuto › Aiuto di Calíope

L'aiuto di Calíope è disponibile come finestra o pannello dedicato con indice, motore di ricerca e navigazione per sezioni. Si apre in modo diverso a seconda della piattaforma ma mostra lo stesso contenuto.

macOS: menu Aiuto › Aiuto di Calíope o scorciatoia ⌘?. La finestra resta fluttuante e può rimanere aperta mentre usi il resto dell'app.

iPad: menu Aiuto › Aiuto di Calíope o scorciatoia ⌘? se hai una tastiera esterna connessa. L'aiuto appare come pannello scorrevole; chiudilo con il pulsante Chiudi nell'angolo in alto a destra o scorri verso il basso.

Aiuto contestuale (?): ogni vista dell'app ha un pulsante ? nella sua barra superiore che apre direttamente l'argomento correlato. È la via più rapida quando sai già quale strumento ti interessa.

Sul web: la stessa guida è pubblicata su https://caliope.org/help/, nelle cinque lingue. Da lì, con «Ho Calíope installato» attivo, ogni argomento ha un pulsante «Apri in Calíope» che lo apre nell'app; il link di un argomento ha la forma caliope://help/<identificatore>.

Parole chiave: aiuto, help, indice, cercare argomento, menu aiuto, ⌘?, documentazione, cmd?