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.
In the Connection Manager, tap + in the left sidebar. Enter a descriptive name, the server type (MySQL, MariaDB, Aurora, PostgreSQL, or MongoDB), the host, port, username, and password. The "Default database" field is optional.
In the Server Options section you can configure the character set, collation, and enable SSL/TLS. If SSL is enabled, fields will appear to select the client certificate and key.
Keywords: profile, new connection, save server, host, configure
Select the profile in the sidebar list. The form on the right loads with its current data and you can edit any field directly. Changes are saved automatically when you connect or select another profile.
Deleting a profile has a topic of its own, because it cannot be undone and takes more with it than you would expect: see Delete a connection.
The three places a profile can be deleted from, what goes with it, and why it cannot be undone.
Where it is: Sidebar › − button (delete connection)
Deleting a connection does not just remove its address and its username: it takes everything Calíope had saved about that server. That is why it asks first, and why the question says the connection's name — if it is not the one you thought, that is the moment to find out.
Where from
- macOS: select the profile and click − in the bar below the list, next to the +. Or right-click the row and choose Delete.
- iPad: select the profile and tap − in the bottom bar; or press and hold the row and choose Delete; or swipe the row from right to left. The swipe does not delete when you let go: it reveals the button, and the question comes all the same. Swiping the other way — left to right — is Move to group.
What goes with it
- The profile and all its data.
- Its password in the Keychain, and also its SSH password and the passphrase of its private key.
- Its query history, and its rows in the error log and in the server message log.
- The SQL it had saved in that connection's editor, and its schema cache.
It cannot be undone. There is no trash and no undo: the confirmation is the only chance to back out.
On your other devices. With iCloud sync on, the deletion travels and the connection disappears there too. The other way round nothing odd happens: a profile you created on the other machine that this one has not seen yet is not read as a deletion, so it is not removed on its own.
A whole group. Deleting a group also deletes the connections inside it, with the same question and the same reach; that is explained in Organizing profiles into groups.
How to use the alternate host when the server address depends on the device you connect from.
Where it is: Sidebar › Connections › Alternate host
The profile’s “Alternate host” field is for a server you can reach at two different addresses. The typical case is a development machine: from the computer itself it answers at 127.0.0.1, while from the iPad you have to use its address on the local network. Because profiles sync across your devices, a single host field cannot be right in both places.
When connecting, the main host is tried first. If it does not answer, the alternate one is tried with the same port, the same user, the same password and the same options: only the address changes. If you also need a different port, write “address:port” (for example, 10.0.0.20:3307).
When the session comes in through the alternate address, a marker appears next to the server name and “Test connection” reports which address answered, so you always know which machine you are working against.
With an SSH tunnel the field is ignored, and that is deliberate: there the server address is resolved by the tunnel machine, not by your device, so it does not change with where you connect from.
Keywords: alternate host, second address, local ip, local network, failover, 127.0.0.1, ipad, two addresses
When you need to write one, which fields Calíope stops using when you do, and where the password ends up.
Where it is: Sidebar › Connections › Connection string
The “Connection string” field only appears when the profile's engine is MongoDB, and it is optional. Leave it empty and Calíope builds the connection from the fields above: address, port, username, password, TLS and database. For an ordinary server that is enough.
Write one when the connection cannot be described with those fields. There are three cases: a replica set, which needs several addresses and the set's name; an authentication database other than the usual one, which is set with authSource; and an Atlas cluster, whose address starts with mongodb+srv:// and has no port to type.
When you write one it overrides the fields above: username, password, TLS and options all come from it. There are two exceptions. If the profile uses an SSH tunnel, the address comes from the tunnel and not from the string, because the server the string names is the one the tunnel machine sees, not your device. And if the string names no database, the profile's one is used, or admin if there isn't one either.
Without a string, authentication goes against admin. That is where administrative accounts live and what both mongosh and Compass assume when someone just types a username and a password; if yours are in another database, say so with authSource.
A warning about the password: the one in the field above is stored in the Keychain, but a password written inside the string is not. The string is saved with the rest of the profile and, if you have iCloud sync on, it travels with it. If that matters to you, leave the password in its own field and use the string only for everything else.
If the string is malformed the connection fails and says so: it is a form error, so it is fixed there rather than by retrying.
Tap Test connection in the profile form. Calíope attempts to open a real connection with the entered details and displays the result in a green banner (success) or red banner (error with description).
The test is especially useful for validating SSL credentials, firewalls, or host configurations before saving the profile.
Keywords: test, verify, check connection, test connection
Once the profile details are complete, tap the Connect button (lightning bolt icon). Calíope opens the MySQL/MariaDB connection pool via MySQLKit and loads the schema tree.
If the connection fails, an error message appears in the status bar. Check the host, credentials, and that the server is running and reachable from your network.
Keywords: connect, open workspace, pool, connection
Switch the session's database context from the SQL Editor.
Where it is: SQL Editor › Database selector
Use the database selector in the SQL Editor toolbar to change the active context without reconnecting. The change is equivalent to executing USE database_name and only affects the current session.
Keywords: use database, change database, select database, switch database
Automatically reconnect if the server closes the session.
Where it is: Sidebar › Profile form › Auto reconnect
In the connection profile form, enable the Automatic reconnection toggle. With this option active, Calíope will attempt to re-establish the connection automatically if the server closes it due to inactivity or a restart.
Useful for long sessions or for servers with a short connection timeout.
Work with multiple MySQL servers at the same time without losing context.
Where it is: Workspace › Server menu
Calíope supports having multiple active MySQL server connections at the same time. Each server has its own independent session with its own schema tree, open SQL tabs, query history, and AI assistant state.
How it works:
Every time you tap Connect in the Connection Manager, a new session is opened without closing the previous ones. All sessions coexist and you can switch between them without losing anything.
Each session's state:
- SQL tabs and their content are preserved when switching servers.
- The schema tree shows the databases of the active server.
- The AI assistant maintains its conversation history per session.
You can open as many sessions as needed — for example, to compare data across development, staging, and production environments simultaneously.
Keywords: multi-server, multiple connections, simultaneous, several connections, sessions, multiserver
Switch between connected servers from the Workspace dropdown menu.
Where it is: Workspace › Server menu
The server selector menu shows the active server name and a connection status indicator (green dot = connected, red = error). Tapping it opens a menu with all open sessions.
On macOS: the selector appears in the window toolbar, in the upper-left corner. It shows the server name, active database, and the dropdown arrow.
On iPad: the selector appears to the left of the tab bar, always visible at the top of the Workspace.
Menu options:
- Tap or click any server name to activate that session.
- The active session is marked with a ✓.
- Add server opens the Connection Manager over the current Workspace to connect another server without losing open sessions.
- Disconnect closes the active server's session.
Keywords: server menu, selector, switch server, switcher, active session, connection indicator
Connect to an additional server without leaving your current work.
Where it is: Workspace › Server menu › Add server
To add a new connection while already working on another server:
1. Open the server selector menu (upper-left corner on macOS, tab bar on iPad).
2. Tap Add server.
3. The Connection Manager opens as a floating panel.
4. Select an existing profile or create a new one and tap Connect.
5. The panel closes automatically and the new session becomes available in the selector.
Previous sessions remain open and intact throughout the process.
Keywords: add server, new session, second connection, connect another server
Close one server's session without affecting other active connections.
Where it is: Workspace › Disconnect
When you have multiple sessions open, you can close any of them independently:
Active server:
- Open the server selector menu and tap Disconnect, or use the red disconnect button in the toolbar.
Any session (switch to it first):
1. Open the server selector menu.
2. Select the server you want to close to activate it.
3. Tap Disconnect.
When a session is closed, Calíope automatically activates the last available session. If it was the only open session, it returns to the Connection Manager.
Keywords: disconnect server, close session, close connection, disconnect, remove server
Encrypt the MySQL server connection with SSL certificates.
Where it is: Sidebar › Profile form › SSL
In the connection profile form, enable the SSL toggle in the Server Options section. Three optional fields appear for client certificates:
- CA Certificate — certificate file from the Certificate Authority (.pem or .crt). Calíope uses this file to verify the server's identity.
- Client Certificate — the client's certificate file for mutual authentication.
- Client Key — the private key corresponding to the client certificate.
If you enable SSL without specifying a CA certificate, Calíope verifies the server certificate against the system trust roots (secure default). If the server uses a self-signed certificate, the connection will fail unless you provide the corresponding CA.
Accept untrusted certificate (insecure): enable this checkbox only if you connect to a development server with a self-signed certificate and cannot provide the CA. The connection remains encrypted but is vulnerable to man-in-the-middle attacks. Do not enable for production servers.
On iPad: use the system file picker to select certificate files from your local storage or iCloud Drive.
The SSL connection is tested when you tap Test connection; the green banner will confirm whether encryption is active.
Require Touch ID or Face ID before connecting to a server.
Where it is: Sidebar › Profile form › Require biometrics
Calíope can protect a connection profile with biometric authentication. When active, the app requests Touch ID (macOS / iPad) or Face ID (iPad with Face ID) before allowing the connection.
Enable on macOS:
- In the profile form, enable Require biometrics in the Server Options section.
- You can also enable it globally from Preferences › Connections › Biometrics.
Enable on iPad:
- In the profile form, enable Require biometrics in the Options section.
- Also available globally in Preferences › General › Require biometrics.
If the device does not have biometrics available or permissions are revoked, authentication fails and the connection does not proceed. Check permissions in System Settings › Privacy & Security › Touch ID (macOS) or Settings › Face ID & Passcode (iPad).
How to group your connections (Production, Development, Client X, etc.) and move profiles between groups on macOS, iPad and iPhone.
Where it is: Connection Manager › right-click › Move to group
As your list of connections grows, you can group them by environment, client, or any other criterion. Groups are collapsible and persist in connections.json as ordered collections.
Create a group
- macOS: right-click on any existing group (or on the sidebar header) and choose New group. It's created with the default name New group and enters edit mode immediately for you to rename.
- iPad: from the Connection Manager, tap the ⋯ menu in the top bar and choose New group, or edit groups from the Manage groups sheet.
Rename / delete
- macOS: right-click on the group name → Rename group or Delete group.
- iPad: to rename, tap the pencil on the row in the Manage groups sheet; to delete, swipe that row right to left. You can also long-press the group header in the list.
- Deleting a group also deletes the connections inside it, along with their saved passwords, their query histories and any SQL they had saved. Before deleting anything, Calíope asks, and tells you how many connections are going and what they are called. This cannot be undone: if what you want is to undo the grouping, move the profiles out first with Move to group ▸ No group.
Move a profile
- macOS: right-click on the profile → Move to group ▸ → choose the target group or No group to remove it from any grouping.
- iPad: swipe the profile left-to-right to reveal the Move action (folder icon, indigo color); the group selection sheet opens.
Reorder groups (iPad)
- Open Manage groups and drag with the ☰ handle to reorder. The order persists in each group's sortOrder field.
Expand/collapse
- Each group has a ▸ to collapse/expand its profile list. The state is saved per group.
Persistence
- Groups and their assignments live in the connections.json file on the current device. If iCloud sync is enabled, they are shared across your devices.
Filtering
- The field above the list leaves only the connections that match; while it has text every group is drawn open without changing what you saved (see Filtering the connections list).
Keywords: group, groups, organize, folder, category, production, development, move profile, drag, swipe, new group, rename, delete group, no group, connections.json
Type in the field above the list to leave only the connections that match, by name, host or group.
When you have thirty or forty profiles, opening a group is no longer enough. The field at the top of the sidebar leaves only the connections that match what you type.
What it searches: the profile's name, its host and its alternative host, the default database, the user name, the engine's name and the name of its group. Typing a group's name therefore shows that group whole — it is how you say show me production. Accents and capitals don't matter.
Groups open by themselves while you are filtering, including the ones you had collapsed, so nothing that matches can stay hidden inside a closed group. That expansion is not saved: clear the field and every group goes back exactly as you left it.
The selection doesn't move. If the profile you were editing falls outside the filter, the form on the right keeps showing it — losing what you were editing because you typed in a search box would be worse than the problem the box solves.
Press Esc or the × to clear the field. The filter is not remembered when you close the app.
How to use Calíope with Amazon Aurora clusters (MySQL-compatible edition) and which features are available.
Where it is: Sidebar › Connection Manager
Amazon Aurora (MySQL-compatible edition) speaks the same protocol as MySQL, so Calíope connects using the same engine, with no special setup.
Create the profile
1. Under Type, choose Aurora.
2. In Host, paste your cluster endpoint (for example my-cluster.cluster-xxxx.us-east-1.rds.amazonaws.com): use the writer endpoint for normal work, or a reader endpoint if you only need to query.
3. Leave the Port at 3306.
4. Fill in username and password as for any MySQL server.
What you get
With Aurora, Calíope offers the same features as with MySQL: SQL editor, schema browser, ER diagrams, backups, and monitoring. A notice in the form reminds you that the available capabilities are the MySQL-compatible ones; you can hide it with Don't show again.
Security
Aurora usually requires TLS: turn on SSL/TLS in the profile and, if your network needs it, combine it with an SSH tunnel to a host inside the VPC.
Note
Aurora-specific features (IAM authentication, distinct cluster endpoints, aurora_% metrics) are not handled specially: Calíope treats the cluster as a standard MySQL server.
Keywords: aurora, amazon aurora, aws, rds, mysql, compatible, endpoint, cluster, engine, server type, mysql protocol
Calíope alerts you when the SSH tunnel drops and when it reconnects automatically.
Where it is: Calíope › Preferences › Notifications
When a profile has SSH Tunnel enabled, Calíope sends local notifications at two moments:
- Tunnel dropped — when a connection failure is detected before attempting to reconnect.
- Tunnel reconnected — if the automatic reconnection (Auto-reconnect profile option) successfully restores the tunnel.
Enable or disable:
Go to Preferences › Notifications and use the SSH tunnel dropped / reconnected toggle.
If automatic reconnection fails, no reconnection notification is sent; the drop was already notified. Cooldown between notifications for the same host is 60 s.