This page describes Calíope 1.5, the version we are building right now. 1.4 is finished and in App Review, and the store serves 1.3 on the Mac and 1.2 on iPad. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Calíope records nothing until you turn it on, and never sends it.
Where it is: Calíope › Preferences › General → Privacy & diagnostics
Recording is off out of the box. Nothing is recorded until you turn it on in Preferences › General › Privacy and Diagnostics › Keep a usage report on this device. While it is off, this file does not grow.
Calíope saves a diagnostic log exclusively on your device, in the file:
Device information (recorded once on launch):
- App version
- Platform (macOS / iPadOS / iOS)
- Operating system version
- Device model (e.g. "MacBookPro18,1")
Connection events:
- connection.opened — MySQL connection established successfully
- connection.ssh.opened — SSH tunnel opened successfully
- connection.error — connection failure (error domain and code; no host or credentials)
- ssh.error — SSH tunnel failure (error type; no host or credentials)
Never logged: SQL queries, database names, hosts, IPs, usernames, passwords, or any schema data.
Keywords: data, privacy, what is stored, events, log, telemetry
How to view the JSON and send it along with your feedback.
Where it is: Calíope › Preferences › General → Privacy & diagnostics
Before there is anything to look at, recording has to be on in Preferences › General › Privacy and Diagnostics. If it is off, the report will be empty — that is not a fault.
You can view the full diagnostic contents in Preferences › General › Privacy and Diagnostics. From there you can:
- Share — opens the system share panel to send it via email, AirDrop, or other apps.
- Copy JSON — copies the content to the clipboard for manual pasting.
- Clear — deletes all logged events.
If you encounter an issue or have suggestions, send the file along with your message to support@caliope.org.
Permanently deletes what Calíope stores on this device and in iCloud, and tells you what was deleted in each place.
Where it is: Calíope › Preferences › General → Delete My Data
The Delete My Data section in Preferences › General deletes what Calíope stores, in all six places where it leaves something.
What gets deleted
Where
What
This device
Connection profiles, query history, error log, AI Assistant history, telemetry, schema cache, recent SQL files, snippets, and monitor entries
Keychain
Connection passwords, SSH key passphrases, and API keys for the cloud providers
iCloud Drive
connections.json, editor state, monitoring configuration, and the scheduled backups folder
Preferences in iCloud
The entire key-value store
Records in iCloud
Query history, AI Assistant history, and error log stored in CloudKit
Widget
The data the widget uses to draw itself
It reaches all your devices. When it finishes, Calíope publishes a notice in iCloud; your iPad and iPhone delete their copy the next time they open. Without that notice, any device still syncing would upload everything again and the deletion would undo itself.
iCloud records are deleted even if syncing is off. The switch says whether things go up from now on, not whether anything is already up there: if you turned it on, uploaded, and later turned it off, your data is in iCloud — and that is exactly what needs deleting.
A restore point is saved before deleting. It is local, it holds your profiles and preferences, and it holds no passwords — there is nobody there to type an encryption key. You will find it in Preferences › Backups. To keep passwords too, export manually beforehand with the secrets checkbox ticked.
At the end you are shown what happened in each place, with the number of items deleted. Anything that could not be deleted appears in red with its reason: without an iCloud session or without a network, CloudKit records cannot be reached from here, and that is not the same as being deleted. Repeat the operation once you are back online; whatever was already deleted is not deleted twice.
What is left alone: files you exported yourself to disk (.sql backups, settings copies, screenshots), because they live outside the app and are yours.
The four iCloud mechanisms Calíope uses: what each one takes off this device, who reads it, and which switch governs it.
Where it is: Calíope › Preferences › General → iCloud
Calíope doesn't have one sync, it has four, and each holds different things. Knowing which is which explains why there are several switches.
1. iCloud Drive — the large files: your connection profiles, the contents of your SQL editor tabs, and the health monitor configuration. Governed by Sync Calíope with iCloud, in Preferences › General › iCloud.
2. Key-value store — preferences and customization: font size, saved snippets, alert thresholds, bar ordering, panel layout. Same switch, and it takes very little space.
3. CloudKit — five channels, each with its own switch, off by default. They sit apart from the general switch because they take data off this device that can be sensitive, and that permission is asked for, not inherited.
- Query history — the literal text of your queries, with table names and values. Switch Sync query log with iCloud, inside the SQL Log itself. Read by your other devices running Calíope.
- AI assistant conversations — your questions and the answers, verbatim. Switch Sync history with iCloud, in the assistant's history panel.
- App error log — your profile aliases and the technical detail of each failure. Switch Sync the error log with iCloud, in Preferences › General › App error log. Read by your other devices running Calíope, your iPhone among them.
- System messages — the profile or server alias, the backup or report name, the machine that produced it, and the figures of the alert (seconds, rows, percentage); never the host, the port, the user, or the text of your queries. Switch Sync messages with iCloud, in Preferences › General › System messages. Read by Calíope on the watch.
- Fleet status — for every monitored server: the alias, host, port, engine, version, and its metrics; and for every replication group you have declared, its name plus each member's label, lag, and state. Never passwords, never the contents of your queries. Switch Publish server status to iCloud, in Preferences › General › Apple TV. Read by Calíope on the Apple TV; turning it off withdraws from iCloud whatever was already published.
4. iCloud Keychain — passwords and SSH keys only, with its own switch in Preferences › General › iCloud. Apple encrypts it end to end.
What never leaves this device, no matter what you turn on:
- The diagnostic log (telemetry.json).
- The schema cache that powers autocompletion.
- The file-access permissions macOS grants you (SSH keys, backup destination folders). These are bookmarks technically, and they're only valid on the machine where you granted them.
- The tabs you had open when you quit, which are deliberately per-device.
Keywords: sync, icloud, what syncs, cloudkit, keychain, privacy, key-value, devices, switches, consent, caliope tv, apple tv, television, watch, companion, iphone, fleet, system messages
Widgets read a local file of metrics, never your credentials.
To draw a widget, Calíope and the widget have to share data. They do it through a shared system folder (an App Group), not over the internet.
What's in that folder:
- Metrics for the server you pinned: active connections, queries per second, uptime, cache hit rate.
- A minimal list of your profiles — name and host — so you can pick a server when configuring the widget.
What isn't there, and can't be: passwords, API keys, SSH keys or query results. Credentials live in the Keychain and the widget never asks for them.
That folder does not sync to iCloud. That's deliberate: it holds derived data that expires in two minutes and that each device rebuilds on its own. It's wiped completely by Delete all my data.
Save your connections, preferences and history to a file, and come back to them whenever you need.
Where it is: Calíope › Preferences › Settings › General
In Settings › General › Configuration backup, “Export…” creates a JSON file with everything Calíope keeps: connections and groups, editor state, preferences and query history. You choose what to include, and whatever is left out is recorded inside the file with the reason — for example recent-file permissions, which only work on the machine where they were granted.
Passwords are separate: they only leave if you tick the box, and always encrypted with a key you type. Without that key there is no way to recover them, not even from Calíope.
When importing you first get a summary of what will change: how many connections are added, how many are updated and — the important one — how many exist only on this device. In “Merge” mode those are kept; in “Replace” they are lost. Before applying anything, the app leaves its own restore point.
Even without passwords, the file carries server names, usernames and the text of your queries: keep it somewhere safe.
Keywords: backup, export, import, restore, configuration, migrate, another machine, JSON
Calíope can save a copy of your configuration every day or every week, and keep it in iCloud.
Where it is: Calíope › Preferences › Settings › General
In Settings › General › Configuration backup you can have Calíope make a copy daily or weekly. Those copies live in your iCloud, so they survive losing the machine and you can restore them from any of your devices.
You decide how many are kept; beyond that number the oldest are deleted. They never include passwords, because they are created on their own and nobody is there to type the encryption key.
The schedule belongs to each device and is not synced: if you want copies from the Mac, the iPad and the iPhone, turn it on in each. And if iCloud isn't available, copies stay on this machine only and the app says so.
Before every operation that could destroy something, Calíope saves a copy by itself.
Where it is: Calíope › Preferences › Settings › General
Beyond the backups you ask for, Calíope leaves an automatic copy right before the operations that can take data away: turning iCloud sync on or off, erasing all your data, restoring a backup, and the first change saved in each session.
These restore points are kept on this machine and never in iCloud, and that's deliberate: their job is to save you from whatever happens to what's in iCloud.
The ten most recent are kept, plus the latest of each kind — so “before turning iCloud on” isn't pushed out by ten routine copies. You can see and restore them in Settings › General › Configuration backup.
Keywords: restore point, undo, before erasing, automatic, local, recover, safety
Logged queries are deleted on their own after the time you choose, both on disk and in iCloud.
Where it is: Calíope › Preferences › Settings › General
In Settings › General › Logging you can choose how long Calíope keeps the queries it logs: 30, 90, 180 or 365 days, or no limit.
The cleanup reaches both places they live: the file on this machine and the iCloud copy, if you have log syncing turned on. It runs once a day, in batches, so a very large log may take several days to be fully trimmed.
“No limit” is a legitimate choice — some people want the complete history — but it's worth knowing what it means: the file grows for as long as the install lasts, and the iCloud copy takes space from your account.
The history you see in the SQL editor is a separate thing: those are the latest queries per connection, kept only on this device and never synced.
Keywords: retention, log, history, delete, days, cleanup, iCloud, space