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.
What has gone wrong in Calíope, when, and on which device.
Where it is: Workspace › Tools › Errors
The Error log stores one row per application failure, with its timestamp in universal time, the device where it happened, the area affected and the connection profile involved, if any.
It is not the query log. That one stores what the server replies to a statement — a syntax ERROR 1064, for instance — which is the normal outcome of writing SQL. This one stores what happens to the app: a connection that won’t open, a tunnel that drops, a backup that can’t be written.
It works offline, and that is deliberate: the log is local and you need to be able to read it precisely when you can’t connect, which is when it matters most.
What is never stored: no password, not even truncated. An authentication failure records that it failed and against which profile, never with what credential. The server is identified by the profile alias, not by host, port and user.
A failure that keeps repeating on its own does not flood the log. The health monitor polls each server every few seconds, so one that is switched off would leave thousands of identical rows overnight. It is recorded the first time, and recorded again if the problem changes, if the server recovers and fails again, or if it is still the same six hours later. Seeing a single row does not mean it happened only once.
Double-click a row (or tap it on iPad) to open the full detail, with the technical text support needs and a button to copy it. If the error has its own explanation, the View solution button is there.
Keywords: errors, log, diagnostics, failures, support
The log can be mirrored into your private iCloud, so what failed on the iPad also shows up on the Mac. Each row keeps the device it happened on: a merged log where you can’t tell who wrote each line is useless for diagnosis.
The switch starts off, and that is not an oversight. A local log is your own file on your own machine; uploading it sends your profile aliases and the technical detail of every failure off the device. That is asked for, not assumed. It lives in Preferences › General, separate from the switch that enables logging: one decides whether it is stored, the other whether it leaves.
Why it doesn’t travel with the other preferences. Preferences move through a small iCloud store with a one-megabyte cap shared by everything; when it fills up, everything stops syncing, not just what filled it. An error log grows with use, so it goes through another channel — CloudKit, record by record — which also lets the Mac, the iPad and the iPhone write at the same time without overwriting each other.
Retention. 90 days by default, adjustable in Preferences. Pruning applies to the local file and to iCloud, so clearing the log doesn’t leave a copy up there to come back on the next sync.
The server didn’t answer: what to check, and in what order.
Applies to:MySQLMariaDBAurora
This error means the connection attempt never got to talk to any server: either nothing is listening on that host and port, or something along the way is blocking it.
In order, from most to least likely:
1. The profile’s host and port. The default port is 3306; a containerised server usually publishes a different one.
2. The server is running. Check from the machine it runs on, if you have access.
3. The SSH tunnel, if you use one. A tunnel failure very often presents as “can’t connect”: look for an SSH error in the log, right before this one.
4. A firewall or the network. A VPN that dropped, a corporate network filtering 3306, or a cloud security-group rule all produce this same error.
5. Which interface the server listens on. A server listening only on 127.0.0.1 is unreachable from another machine even while running; the answer there is an SSH tunnel, not opening the port.
The connection got through, but the credentials aren’t valid from here.
Applies to:MySQLMariaDBAurora
This error is half good news: it means the network works and the server is alive. What fails is the identity.
Three causes, fixed differently:
- The password or user name isn’t what the server expects. Check them in the connection manager. Watch for leading or trailing spaces when pasting a password.
- The account exists, but not from this machine. In MySQL and MariaDB an account is the pair user + origin host: dba@localhost and dba@% are different accounts with different passwords. If you connect through an SSH tunnel the server sees you arriving from localhost; without a tunnel, from your IP. This is the most common cause of “it works from one place and not another”.
- The account has no rights on that particular database. If the message names a database, the user got in but can’t use it; a GRANT on it is missing.
The User administration tool shows, for each account, which hosts it may connect from and what privileges it holds.
Either it was dropped, or renamed, or your account can’t see it.
Applies to:MySQLMariaDBAurora
Calíope remembers the last database you used in each profile, so this error usually shows up when reconnecting to a server that has changed.
What to look at:
- Letter case. On Linux, database names are case-sensitive by default; on macOS and Windows they aren’t. A database created on a laptop and looked for on a Linux server may go missing for that reason alone.
- Privileges. An account with no rights on a database doesn’t see it in the list, so “doesn’t exist” and “you can’t see it” look very much alike from here. If another user does see it, this is it.
- The wrong server. With several similar profiles it is easy to be looking at production while believing it is staging.
Refresh the schema tree to see the list the server actually returns right now.
It broke mid-operation: why it happens and what is left half done.
Applies to:MySQLMariaDBAurora
The connection was established and then dropped. The important part isn’t reconnecting — that’s easy — but knowing what was left half done.
If a write statement was running outside an explicit transaction, it may have been applied fully, partly or not at all, depending on where it was cut. The query log tells you which one went out last; check it on the server before repeating it.
Usual causes:
- Server wait timeout. A connection idle for longer than wait_timeout (8 hours by default, though many servers lower it to minutes) closes by itself. It shows up as “it dropped right when I came back to the app”.
- A query taking longer than allowed. What runs out there is net_read_timeout, or a limit in a proxy sitting in between.
- A packet that is too large. An INSERT exceeding max_allowed_packet closes the connection instead of returning a readable error.
- The network. Switching Wi-Fi, sleeping the machine or a VPN reconnecting all cut the connection without warning.
SSH authentication failed: key, password, and the second-device case.
The tunnel reached the SSH server but couldn’t identify itself. The database hasn’t even been attempted yet.
The most confusing case: you have just set up your other device. Profiles sync through iCloud, but permission to read your private key file does not, and that isn’t an oversight: such permission is a reference to the file system of one machine and means nothing on another. On the new device you must pick the key file again in the profile. This is the number-one cause of “the same profile works on the Mac and not on the iPad”.
Everything else, in order:
- The SSH user isn’t the database user. They are two separate identities and often different names.
- The public key isn’t on the server. It has to appear in that user’s ~/.ssh/authorized_keys, on that machine.
- File permissions on the server. An authorized_keys readable by others makes the server ignore it silently, without saying why.
- The key passphrase. If the key is protected you have to type it; a protected key without its passphrase behaves exactly like a wrong key.
When it is normal, when it isn’t, and how to check before accepting.
The first time you connect to an SSH server, Calíope stores its key fingerprint. If on a later connection the server presents a different one, it stops and warns you.
This warning isn’t bureaucratic noise. A key change is exactly what an interception between your machine and the server looks like: accept the new key and you would be handing over your credentials without knowing.
When the change is legitimate:
- The server’s operating system was reinstalled.
- The virtual machine or container was recreated.
- The name or IP was reassigned to a different machine (common in the cloud).
How to check properly: ask whoever administers the machine for the fingerprint, through a channel other than the connection itself — a message, a call — and compare it with the one shown in the warning. If it matches, accept. If you can’t check it, don’t.
Keywords: ssh, host key, fingerprint, security, man in the middle
Supported formats, and why the file stops being readable on its own.
Calíope carries its own SSH implementation and doesn’t use the system’s ssh, so it supports a specific set of formats: ed25519 and ECDSA keys in OpenSSH format.
If the file exists but won’t read:
- The permission may have expired. Calíope only reaches files you pick yourself in a dialog, and that permission is stored as a reference that sometimes stops being valid: if you move the file, rename the folder or restore the machine from a backup, you have to pick it again.
- It may be an old RSA key. Convert it to ed25519, which is also faster and shorter.
- You may have picked the public key. The right file is the one that does not end in .pub.
- It may be passphrase-protected. Then you have to type the passphrase when connecting; without it the key can’t be decrypted and the result is indistinguishable from an unreadable file.
It drops every few minutes: nearly always the server closing idle sessions.
The tunnel was open and then wasn’t. Reconnecting the profile fixes it, but if it happens often there is a specific cause you can remove.
The most common one is the SSH server itself closing idle sessions. Many sshd setups have ClientAliveInterval and ClientAliveCountMax tuned to disconnect after a few minutes without traffic. Since a database working session has long stretches of reading without sending anything, the tunnel drops right as you come back to the app.
Other causes:
- The machine slept. On waking, the network connections it had are no longer valid.
- A network change. Going from Wi-Fi to Ethernet, or between Wi-Fi networks, changes the source address and cuts the session.
- A concurrent session limit on the server, if several people share the same SSH user.
The Activity panel shows the tunnel as an active mode while it lives, so you can see at a glance whether it is still open.
What Calíope needs from iCloud, and what stops working without it.
Calíope uses iCloud to carry your profiles, your preferences and — if you enable it — your logs from one device to another. With no active account, all of that stays local.
What to check:
1. That you are signed in to iCloud in System Settings.
2. That iCloud Drive is on, not just the account.
3. That Calíope appears in the list of apps allowed to use iCloud Drive. This is easy to miss: the account can be fine while the app is unchecked.
Nothing is lost meanwhile. Everything is still stored on this device; what doesn’t happen is the copy to the other one. As soon as iCloud comes back, sync catches up by itself.
A failed upload doesn’t lose data; what to do if it keeps happening.
First: nothing has been lost. Everything Calíope syncs has its copy on this device, and the upload is an extra copy. A failure here means the other device will see the data later, not that it was deleted.
If it happens once and doesn’t return, it was almost certainly the network. It retries by itself.
If it keeps happening:
- Check your account storage. A full iCloud produces this error consistently.
- See whether there are too many writes in a row. Calíope batches uploads precisely to stay under iCloud’s rate limit, but a first upload of a very large log can take several attempts.
- Turn the failing sync off and on again. Re-enabling it uploads everything from scratch.
Before touching anything, make a copy. Preferences has a full settings export; it exists because a badly executed sync activation can replace the container’s connections file with an empty one. That is a measured incident, not a hypothesis.
What takes up space in Calíope, and what you can trim without losing anything important.
Calíope stores very little in iCloud by default: your connection profiles and preferences take a few kilobytes.
What grows with use are the logs, and only if you enable them: the query log and the error log. Both have configurable retention in Preferences, and lowering it is the most direct way to reclaim space without losing anything you were looking at.
What to trim, by effect:
1. The query log’s retention days. By far the biggest: it stores the full text of every statement.
2. The error log’s days.
3. The AI assistant history, if you have it synced.
Clearing any of the three from its own tool also deletes the iCloud copy, so the space really comes back and doesn’t return on the next sync.
None of this touches your working data: databases live on their servers and Calíope never copies them to iCloud.
Keywords: icloud, storage, quota, retention, log, clean up
Calíope runs in a sandbox, which is an App Store requirement: it can’t open a file by path, only the ones you explicitly pick in an open or save dialog.
That has a practical consequence that surprises people the first time: typing the path by hand isn’t enough. Even if the file exists and is yours, if it hasn’t gone through a dialog the app can’t see it.
How permission is granted: open the file or folder with Open… or Save as…. From then on Calíope stores the permission and can reuse it without asking.
When it has to be granted again:
- If you move or rename the file or its folder.
- If you restore the machine from a backup.
- If it is another device. These permissions deliberately don’t sync: on another machine they mean nothing.
It is the same reason an SSH private key or a scheduled-backup folder has to be picked again on each device.
Why a file that used to work stops opening without you touching anything.
When you pick a file in a dialog, Calíope doesn’t store its path: it stores an access permission, a reference issued by the system that can expire. Once it does, the app can no longer open the file even though it is still in the same place.
What invalidates it:
- Moving, renaming or re-creating the file.
- Renaming any folder along its path.
- Restoring the machine from a backup.
- The file living on an external or network volume that was unmounted.
And there is a case that isn’t a bug but a rule: these permissions don’t sync between devices, and not out of carelessness. Such a permission is a reference to the file system of one particular machine; on another it points at nothing, and carrying it over produces failures with no visible explanation — typically an SSH authentication that fails for no apparent reason.
The fix is always the same: pick the file again. Nothing else is lost; you just have to grant access once more.
What it intercepts, why, and how to run it anyway if you’re sure.
Safe Mode inspects statements before sending them and stops the ones that can destroy data irreversibly: DROP, TRUNCATE, and DELETE or UPDATE without a WHERE clause.
It is not a privilege restriction. Your account may be perfectly entitled to do it; what Safe Mode does is make you confirm that this is what you meant. It exists for the one-second mistake: the DELETE whose WHERE was left out because you half-selected it before running.
To run it anyway, turn Safe Mode off in the SQL editor bar and launch it again. The switch is in plain sight, not buried in preferences, precisely so that turning it off is a conscious and momentary act.
Practical advice: leave it on for production profiles and off for development ones. The setting is per profile, so you don’t have to keep remembering.
Where to enter it, where it is stored, and why it doesn’t travel with your settings.
Where it is: Calíope › Preferences › AI Assistant
The SQL assistant uses an external provider, and it needs an API key of yours to talk to it. You enter it in Preferences › AI Assistant.
Where it is stored: in the system Keychain, not in an app file. That means neither the settings backup nor ordinary sync carries it by default: a secret only leaves this device if you explicitly ask for it and encrypt it with a password you choose at that moment.
If you have just set up another device and the assistant doesn’t work there, this is why: the key has to be entered on each device, or Keychain sync has to be enabled in Preferences.
Calíope doesn’t sit in the middle of that relationship. The key is yours, it goes straight to your provider, and usage is billed to your account. That is why usage limits and balance are managed in the provider’s dashboard and not here.
Keywords: api key, assistant, ai, keychain, provider
Provider usage limits, and what you can adjust from Calíope.
The quota isn’t set by Calíope: it comes from the AI provider you configured, according to your plan and balance.
Two different limits that produce the same error:
- Rate. Too many requests in a short time. Waiting a minute clears it.
- Spend. The credit or the period’s allowance ran out. That has to be topped up in the provider’s dashboard.
What you can adjust here: in Preferences › AI Assistant you can lower the maximum tokens per answer, which is the biggest consumer, and switch to a cheaper model. A long conversation also costs more, because the history travels with every request: starting a new conversation reduces the cost of the following ones.
The rest of the program works exactly as before. The assistant is just one more tool; nothing you do with the SQL editor, backups or catalogues depends on it.
The database is left in an intermediate state: how to find where it stopped and what to do.
Where it is: Workspace › Tools › Backup
Applies to:MySQLMariaDBAurora
A restore applies the file statement by statement. If it stops, what was applied up to that point is applied: the database doesn’t roll itself back.
First: don’t assume it is fine. A half-restored database has complete tables, empty tables and missing tables, and at a glance it can look like it works.
Where to look: the error’s technical detail says which statement it stopped on. It is usually one of three things:
- A table that already existed. Restoring onto a non-empty database collides on the first repeated CREATE TABLE.
- A DEFINER that doesn’t exist on this server. Views, routines and triggers carry the user who created them; if that account isn’t here, they fail. Calíope strips that clause when it generates its own backups, but a file made with another tool may carry it.
- A statement size limit. A backup taken against a server with a high max_allowed_packet produces statements that a server with the default value rejects.
How to get out: the cleanest route is to drop the database and restore from scratch onto an empty one. Resuming from the middle requires knowing exactly what was applied, and the file doesn’t carry that information.