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.
Monitor active connections, QPS, and server status from the home screen or desktop without opening the app.
Where it is: Widget › General
The Calíope Widget displays key server metrics —MySQL, MariaDB or PostgreSQL— in real time directly on the macOS desktop or iPad home screen, without needing to open the application.
Displayed metrics:
- Active connections — number of open connections and the maximum configured on the server.
- QPS or TPS — the server's throughput: queries per second on MySQL and MariaDB, transactions per second on PostgreSQL. They are two different magnitudes, so the label tells you which one you are looking at.
- Uptime — server online time in Nd Nh Nm format.
- Active threads (medium and large widget sizes) — number of running threads.
- Slow queries/sec (medium and large) — slow query rate.
- Cache hit (medium and large) — percentage of reads served from the server's cache.
- Status badge — green (active and fresh data), red (the server stopped answering on the last poll) or amber (the data can no longer be presented as current). When there is no data yet there is no badge at all: the widget asks you to choose a server and claims nothing else.
- Connection bar — visual bar with semantic color: cyan (low), amber (>65%), red (>85%).
Available sizes:
- Small — active connections with their bar, the server name and the status badge. Nothing else: this is the size where the figure has to fit whole.
- Medium — adds the throughput, active threads and the cache hit rate — or uptime instead, if the engine doesn't publish cache figures.
- Large — all of the above plus uptime and slow queries per second.
- Extra Large — the same, laid out in two real columns. On iPad it goes on the home screen; on the Mac only on the desktop, because Notification Center doesn't accept this size.
- Lock Screen — rectangular (iPad) — server name, active/max connections and QPS.
- Lock Screen — circular (iPad) — ring showing the connection usage ratio with the absolute number in the center.
- Lock Screen — inline (iPad) — a single line next to the clock showing the number of active connections.
How to add the widget:
- macOS: right-click on the desktop and select Edit Widgets. Search for Calíope and drag the desired size to the desktop or Notification Center.
- iPad: long-press the home screen until icons jiggle, tap Edit in the top-left corner, then Add Widget, search for Calíope, and select the size.
Update frequency:
You choose the cadence, and everything else follows from it. With the Dashboard open, metrics are written at the rate of its refresh picker (1 to 30 seconds). With the Dashboard closed, you need to turn on Preferences › Widget › Background refresh and pick the interval there: 30 seconds, 1, 5 or 15 minutes.
When the badge turns amber:
When the data has gone more than three times that cadence without being renewed, with a floor of 90 seconds. With the interval at 5 minutes the widget stays green for 15; at 15 minutes, for 45. The ceiling is derived from your setting instead of being a fixed number, because a widget that turns amber while the refresh is working exactly as configured is not warning you about anything.
And if there never was any data — because you have not picked a server — the widget does not say No data: it asks you to pick one.
A second widget that shows the whole fleet instead of a single server: how many are watched, how many need attention and which one is worst.
Where it is: Widget › Widget, gallery, Home Screen
The Metrics widget looks at one server. This one looks at all of them, and answers a different question: is there anything I should go and look at?
Where it works
- iPhone and iPad. On macOS only the metrics widget is available.
Sizes available:
- Small — the worst state in the fleet and how many servers are watched.
- Medium — the list, up to three servers, worst first.
- Large — the same list, up to six. In both, whatever doesn’t fit is spelled out as “and N more”, and at accessibility sizes fewer rows fit.
Where the data comes from
- The Health Monitor, in this same app. Every poll writes the result to the container the widget reads.
- It does not travel over the network and it does not depend on iCloud: what you see on the Home Screen was measured on this device.
- If iCloud publishing is off, the widget keeps working. That switch decides what leaves the device, not what your own screen shows you.
When it says nothing
- Open the Health Monitor once: nothing has been measured on this device yet.
- No server is being watched: the monitor ran and there is nothing in its list.
Colour is never the only signal: every state carries its own shape, and the reading order of VoiceOver states the count, the worst one and how many need attention.
Touching it opens the Health Monitor.
Keywords: fleet, widget, health, monitor, home screen, servers, severity
A tap or click on the widget opens Calíope and connects automatically to the pinned server.
Where it is: Widget › Deep link
When you tap or click the Calíope widget, the app opens and connects directly to the server that widget has chosen, taking you to the Dashboard of the corresponding workspace.
How it works:
- The widget includes a deep link of the form caliope://server/<id> pointing to the server chosen in that widget's configuration, not to whatever it happens to be showing. The difference matters when there are no metrics yet: the widget says “Choose a server” and still opens its own.
- If the app wasn't open, it launches first and then opens the session.
- If the app was already open and an active session for that server exists, it simply brings it to the front.
Which server it opens:
- The one you picked when adding the widget, or whatever you set afterwards: long-press the widget (iPad) or right-click it (Mac) → Edit Widget → Server.
- If that widget has none chosen, it opens the one behind the data it is showing, which is the last active Dashboard.
- The pinned profile in Preferences › Widget is a different thing: it is the server that gets refreshed in the background, not the one the link opens.
If no server is selected, the widget asks you to pick one; tapping it opens Calíope at the Connection Manager screen.
Every widget can monitor a different server — set it when adding the widget or edit it later.
Where it is: Widget › Configuration
The Calíope widget is configurable: when adding it to the Desktop or Home Screen, the system asks which server it should display. You can have several widgets on screen at once, each showing metrics from a different server (production, staging, replica, etc.).
Configure when adding the widget
- macOS: right-click the Desktop and choose Edit Widgets, then drag the variant you want onto the desktop. Dropping it does not open any picker: you choose the server afterwards, by right-clicking the placed widget → Edit “Calíope” → Server.
- iPad: long press the Home Screen, tap Edit → Add Widget, search for Calíope and pick the size. You choose the server afterwards, by long-pressing the placed widget → Edit Widget → Server.
Change the server of an existing widget
- macOS: right-click the widget → Edit "Calíope" → change the Server parameter.
- iPad: long press the widget → Edit Widget → change the Server parameter.
What is shared through the App Group
- Calíope publishes a minimal catalog (id, name, host) of your profiles when the app launches and every time you save changes in the Connection Manager. The widget reads that catalog to populate the picker; only profiles whose engine can publish metrics go into it —MongoDB ones are not offered, because choosing one would leave the widget empty forever— and it never sees passwords, SSH keys or certificates.
- Metrics are stored per profile (caliope_widget_metrics_<id>.json), so each widget reads its own data regardless of which session is active in the app.
Widget without a configured server
- If you don't pick a server, the widget shows the metrics of the last active server in the app. But if you do pick one and there are no metrics for it yet, it will not show someone else's: it says there is no data. A widget pinned to a server can never end up showing another server's name and figures.
How Calíope shares metrics with the Widget extension on all three.
Where it is: Calíope › Preferences › Widget
The Calíope widget lives in a separate extension that cannot read the main app's memory. For real-time data to appear, the app and the extension share a common container through an App Group.
Identifier
- iPad: group.org.caliope.widget.
- macOS: the same one prefixed with the team identifier (ASH9Q9BLUY.group.org.caliope.widget) — the system requires that form there.
The same container feeds the two iOS widgets: the metrics one and the fleet health one. On iPhone and iPad it is the same binary, so it is the same App Group.
What is shared
- The most recent metrics of each server (active connections, throughput —QPS or TPS depending on the engine—, uptime, threads, slow queries/s, cache hit rate).
- The timestamp of the last update and the cadence it was written with. The widget uses both to decide when to turn the badge amber: the ceiling is three times the cadence, with a floor of 90 seconds.
- The pinned profile identifier and the URL caliope://server/<id> for the deep link.
How it is updated
- While the main app is open and connected, WidgetDataStore writes to the App Group every time a polling tick arrives.
- After writing, Calíope calls WidgetCenter.shared.reloadAllTimelines() so the widget refreshes on the next opportunity granted by the system.
- If the app closes, the widget keeps showing the last data until the system requests a new timeline. Past the ceiling derived from the cadence, the badge turns amber and the label becomes No data.
Reinstalling the app or changing Apple ID
- The App Group is tied to the developer's Team ID. When you install Calíope from Mac App Store or App Store, macOS/iOS creates the container automatically. No configuration needed.
- If you transfer the iPad to a different Apple ID, the container is removed along with the app and the widget stays empty until you open Calíope at least once again.
The language does not travel through here. It is chosen per application in the system settings, and that choice reaches the extension too: the widget reads its own and speaks the same one as the app without anyone having to hand it over.
Step-by-step diagnosis when the badge is amber and no metrics appear.
Where it is: Widget › Troubleshooting
If the Calíope widget shows the amber badge with the label No data, it means the data has gone too long without being renewed. "Too long" is not a fixed number: it is three times the cadence it was written with, with a floor of 90 seconds.
First, look at what the widget actually says:
- Choose a server — there has never been any data. That is step 1.
- No data — there was, and it has expired. That is everything else.
- Offline, in red — the background refresh tried to poll and the server did not answer. The figures you see are the last true ones, which is why they are dimmed.
1. Is a server selected?
- Each widget picks its own: long-press (iPad) or right-click (Mac) the widget → Edit widget → Server.
- If you pick none, the widget falls back to the last server active in the app; with none of those either, it has nothing to show.
2. Who is writing the metrics?
There are only two writers, and with neither of them running the widget stands still by definition:
- The Dashboard open on that server. When you close the tab the figures stay: the widget keeps showing the last measurement and marks it as old when the time comes. They used to be deleted on close, which left every widget with nothing exactly when you quit the app.
- The background refresh, in Preferences › Widget. You have to turn it on and pick the pinned profile there; that is what keeps the widget alive with the app in the background.
3. What if the interval is long?
At 15 minutes the widget stays green for 45 and then turns amber even though everything works: time between two writes has simply passed. If you want amber sooner, lower the interval in Preferences › Widget.
4. Did you restart the device?
After a restart the widget has no state until the main app runs at least once again.
5. Is the system blocking it?
- On iPad, Settings › General › Background App Refresh must be enabled for Calíope, or the scheduled refresh never gets to run.
- On Mac there is no equivalent, but there is also no one writing while Calíope is closed: the widget keeps the last thing it received and marks it as old when due.
6. If none of the above fits
Remove the widget from the desktop or Home Screen and add it again: that forces the system to rebuild the timeline from scratch.