This page describes Calíope 1.5, the version I am building right now. 1.4 is on the App Store for the Mac, iPad, iPhone, Apple Watch, Apple TV and Apple Vision Pro. 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 family (the protocol it speaks) and the product within it, then host, port, user 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. There is no Save button: every change is saved as you make it.
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 connection pool with the engine's driver 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 from the schema panel.
Where it is: SQL Editor › Schema panel › Set as active database
In the SQL Editor's schema panel, right-click a database and choose Set as active database. The session switches to it without reconnecting — it is the same as running USE database_name — and the server menu shows its name next to the server's. The change 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 servers at the same time without losing context.
Where it is: Workspace › Server menu
Calíope supports having multiple active 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 (in the window toolbar on macOS, the tab bar on iPad).
2. Choose Add server.
3. The Connection Manager opens: in a window of its own on macOS, as a sheet on iPad.
4. Select an existing profile or create a new one and press Connect.
5. The Connection Manager closes by itself and the new session is 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 connection to the server 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.
Where the file lives: when you choose a CA, a certificate or a client key — or paste it, on iPad — Calíope keeps its own copy on this device, never in iCloud Drive, and the profile points to that copy. You can move or delete the original afterwards, and on the Mac it is still read after relaunching. To renew a certificate, choose it again, even if it has the same name. The file stays on the device where you chose it, and so does its location: a profile set up on another device arrives without it. Before you connect, the connection list shows Choose its files on this device and the form says “This profile uses a certificate chosen on another device: choose it here.”; choose it there, and from then on that device keeps its own copy.
If a file cannot be read, Calíope does not connect without it: it stops with “Couldn’t read a TLS file”, naming the file and which of the three it is.
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 any server.
Where it is: Sidebar › Preferences › General › Security
Calíope can ask for Touch ID (Mac) or Face ID (iPad and iPhone) before opening any connection. It is one switch for the whole app, not a setting of each profile.
Where to turn it on
- Preferences › General › Security › Require Touch ID to connect (or Require Face ID to connect), on the Mac and on the iPad alike. It only appears if the device has biometrics available.
With it on, Connect asks first, and if the authentication fails the connection does not proceed. Testing a profile does not ask. Check the permissions in System Settings › Touch ID & Password (Mac) 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.
What a family is, what a product is, and how Calíope proposes the product the server says it is when you test the connection.
Where it is: Sidebar › Connection Manager
Calíope groups servers by family, which is the protocol it speaks: MySQL / MariaDB, PostgreSQL, SQL Server and MongoDB. Within each family you choose the product: the specific name of what you have in front of you.
Families and products
- MySQL / MariaDB: MySQL, MariaDB, Amazon Aurora MySQL and "Other MySQL-compatible".
- PostgreSQL: PostgreSQL, Amazon Aurora PostgreSQL and "Other PostgreSQL-compatible".
- SQL Server: Microsoft SQL Server.
- MongoDB: MongoDB and "Other MongoDB-compatible".
What each one decides. The family decides which engine Calíope connects with and which tools are offered. The product sets the name, the terminal prompt and the snippets that get seeded; Aurora MySQL, for instance, brings its own. A product that is not its family's reference shows a notice in the form as a reminder; you can hide it with Don't show again.
Creating the profile
1. Under Server (Type on iPad and iPhone), choose the family.
2. Under Product, which on the Mac is the menu next to it, choose the product. If yours is not listed, choose "Other … compatible".
3. Fill in host, port, user and password as usual. With Aurora, paste the cluster endpoint and enable SSL/TLS.
The server says who it is. When you press Test connection or load the list of databases, Calíope asks the server and, if it identifies itself as another product of the same family, proposes it below the selector: press Use … to correct the profile, or ignore it. It never changes it on its own. MongoDB is not asked.
Note
Product-specific features (Aurora IAM authentication, differentiated endpoints, aurora_% metrics) get no special treatment: Calíope handles the server as a standard member of its family.
SQL Server connects to version 2022 or later, always encrypted. A SQL Server profile synced to a device that still has Calíope 1.4 shows there as MariaDB, because that version doesn't know the family; opening it there won't work until that device updates.
Keywords: family, product, aurora, amazon aurora, aws, rds, mysql, mariadb, postgresql, mongodb, compatible, protocol, detect, server type
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.