Getting Started

Application overview and main workflow.

Calíope is a native client for MySQL, MariaDB, PostgreSQL, Microsoft SQL Server, Oracle Database, ClickHouse, MongoDB, and Redis, on macOS, iPad, iPhone and Apple Vision Pro. The main workflow revolves around two screens: the Connection Manager, where server profiles are managed, and the Workspace, which opens once a connection is established.

The Workspace contains the Tools sidebar —the schema tree lives inside the SQL Editor—, a tab bar for opening multiple tools simultaneously, and a quick-access toolbar for all available tools.

Keywords: start, overview, introduction, what is, getting started, welcome

One file brings up as many as forty test servers, already seeded: you choose which.

If you have no server at hand, or you want to see what Calíope can do before pointing it at one of yours, you can bring up the very test environment I develop the app against. It is a single file and it needs nothing but Docker.

→ Download caliope-testbed.command

What you need. A Mac with Docker Desktop — free for personal use, at docker.com — and disk: about 39 GB with everything, 14 of them Oracle's image, which grows over time because the load generators keep writing. Memory depends on what you start: with everything up it is about 15 GB for Docker, and neither SQL Server nor Oracle will start with less than 2 GB free. Before starting, the launcher itself tells you how much memory your choice needs and how much Docker has.

How to start it. The cleanest way is to paste these four lines into Terminal:

cd ~/Downloads
curl -fLO https://caliope.org/caliope-testbed.command
chmod +x caliope-testbed.command
./caliope-testbed.command

If you would rather download it with your browser, two more things are needed, in this order: make it executable (chmod +x on the downloaded file) and open it the first time with right-click › Open instead of a double click, because macOS quarantines whatever a browser downloads. With curl neither applies.

First it asks what to start. Opened in Terminal, the launcher walks through the engines with you: you type the numbers of the ones you want and, for each, pick the minimum, everything or custom, with what each piece weighs next to it. Dependencies sort themselves out: a tunnel node brings the SSH bastion, and ClickHouse's second shard brings the replicated pair. Then it offers the sample datasets of the engines you chose — Sakila for MySQL and MariaDB, Pagila for PostgreSQL and the Atlas sample for MongoDB —, which download in the background while the containers start and load as soon as their nodes are up; if they were already loaded, they are not downloaded again. Everything that finishes is announced with a line in the terminal and a macOS notification. Next time, every answer defaults to the previous one, and Enter repeats the whole start. Whatever was running from before and you did not choose is stopped, keeping its data.

It tells you what it is doing while it works, and when it finishes it prints one report with the addresses, the ports, the credentials and the state of each replication group.

What it can bring up. As many as forty servers, picked so that no Calíope tool is left with nothing to show:

Plus an SSH bastion and continuous load generators, so the Dashboard, the slow query log, the process list, the replication monitor and the topology have real traffic to show.

You do not type the profiles in. Every run leaves a caliope-testbed-connections.json file next to the launcher, with the nodes it started as one group. In Calíope: Settings › Connections › Import. Importing merges, so nothing you already have is removed. Each profile already carries its user and password: caliope and caliopepass in almost all of them, caliope_admin in ClickHouse, sa with Caliope!pass1 in SQL Server and system with Caliope_pass1 in Oracle. The tunnelled profiles — up to five — ask for their SSH password (tunnel123) the first time, because SSH secrets only ever live in the Keychain.

From the iPad and the iPhone too. Every profile carries the Mac's network address as its alternate, so the same file works on all your devices without editing anything — with the Mac awake, the testbed running, and both on the same network.

On another machine. With --remote, the same launcher brings the testbed up on the Docker of another machine on your network — a Linux box with SSH —, and sets it up the first time: it asks for its address and user, installs an SSH key and, if missing, Docker. That way the memory and CPU it uses are not your Mac's.

The commands.

Careful with --fresh: it is destructive and it reaches beyond Calíope. It stops every Docker container on that machine and deletes images, volumes and caches nothing is using, including those of your other projects. It says so and asks for confirmation before touching anything.

This is not a server to work on. The passwords are public and written inside the file itself, nothing is encrypted, and everything listens on your machine. It is a testbed: for learning, for trying a tool before you use it on data of your own, and so that a bug report can be reproduced.

Keywords: docker, test, testbed, sample, no server, demo, practice, sakila, replication, wizard

An ~80 MB SQLite file with real products and images, for the SQLite Editor and File Previewer.

If you want to see how Calíope behaves with a large, realistic file — or simply try the SQLite Editor and the File Previewer without any server on hand — you can download a sample database that's already loaded.

→ Download caliope-demo.db

What it has. About eighty megabytes spread across two related tables: productos, with roughly fifteen hundred items — name, description, price, stock, date added, category, and a handful of JSON attributes —, and imagenes, with several real photos per product: each one is an actual PNG, not filler. It also has its indexes, the foreign key between the two tables, and a view (vista_catalogo) that joins them.

Some products have no category, description, or attributes: that's on purpose, so you can see what null values look like.

All the text is in Spanish, with accents, ñ's, and the occasional emoji, so you can check at a glance that UTF-8 handling is correct.

How to open it. Download it and open it from the SQLite Editor with Open…; it's treated like any other .sqlite/.db file, with no connection needed.

It doesn't update itself. It's a static file, and each time it's regenerated it can end up a slightly different size.

Keywords: sqlite, demo, sample, example, images, blob, test, no server, offline, utf-8

Create a profile and establish your first server connection.

Where it is: Connection Manager › + Button

In the Connection Manager, tap the + button in the sidebar to create a new profile. Enter the host, port (the form proposes each engine’s default), username, and password. Tap Test Connection to verify the details before saving.

Once validated, tap Connect to open the Workspace. The profile is saved and will be available in the list for future connections.

Keywords: first time, new connection, profile, host, port, connect

How to use the Tools sidebar, the tabs, the server switcher and the status bar.

The Workspace has three zones: the Tools sidebar on the left, the tab bar with the tools you have open, and the status bar at the bottom.

To open a tool, click its row in the sidebar. Each one opens in its own tab; you can keep several open and move between them with ⌘} and ⌘{ on the Mac (⌘] and ⌘[ on iPad). Rows are grouped by theme, and both the order and the groups are adjusted from the ⋮≡ button in the sidebar itself (see Customize the main bar). Each group collapses when you click its header, and the field at the top of the sidebar filters the tools by name (see Filtering and collapsing the Tools sidebar).

Server switcher: the menu with the active server's name sits in the top-left corner (macOS) or to the left of the tab bar (iPad); on iPhone it is also at the top of the Tools list. From there you can switch sessions, add another server or disconnect. Calíope supports several active connections at once.

Hide the sidebar: the title-bar button collapses it and gives the full width to the active tool.

The schema tree is not here: it lives inside the SQL Editor, the only place it is useful.

Offline: the Workspace without a server shows a quick-access strip with what needs no connection — SQL Editor, Snippets, SQLite Editor, DuckDB Editor, File Previewer, Errors and Reports. The chevron at its right end collapses it.

On iPhone and in a narrow window: the tools live in a bottom bar with the first four of your order and a More button for the rest. Which four those are is up to you: reorder the sidebar.

Apple Vision Pro: the tool navigator hangs outside the window, on its left, and the tab bar above it, with the server switcher in front and, at the end, activity, keep awake, Help and Settings. Each tool's header hangs below the window. There is no title-bar button to hide the sidebar: the View menu does it. See Calíope on Apple Vision Pro.

Keywords: workspace, sidebar, tools, tabs, navigation, server switcher, status bar, offline

The navigator's list is decided by the connection, not by a setting you changed.

The tool navigator doesn't always show the same list: it shows what this session can do. On connecting, Calíope works out what that connection knows how to do and hides the rest. What you can't see isn't broken or switched off: it isn't offered.

Hiding it is deliberate. A tool that opens only to say "not here" has already wasted the trip, and a greyed-out row invites you to hunt for the switch that turns it on — and there is none.

Because of the kind of database. A relational server and a document server are not alike: a document session has no SQL editor and no entity-relationship diagram, and a relational one has no collection browser. That never changes, and it isn't a shortcoming of either.

Because of what that connection can do. Two relational servers don't offer exactly the same things either. Sometimes the engine has no such concept, and then the tool will never appear against that server because there would be nothing to show; sometimes Calíope hasn't written it for that engine yet, and it will appear in a later version. Both absences look the same on purpose: what you need to know right now is whether the tool works, not why it doesn't.

Because of the connection's tag. If the connection carries a read-only environment tag, the tools that only write are hidden as well —the Table Builder, User admin, Table maintenance and Data migration—, and if one is asked for, the status bar says the session is read-only. Changing the tag brings them back, without reconnecting.

Without a connection the navigator shows only what works with no server: the SQL Editor, Snippets, the SQLite Editor, the DuckDB Editor, the File Previewer, Errors and Reports — the last one only halfway, because with no server they can be viewed, edited and exported, but not run.

Where else you'll notice. The Go button in this Help can point at a tool your session doesn't offer: then nothing opens and the status bar says so by name. That's an answer, not a failure.

And this Help carries them all. The index doesn't change with the server you're connected to, so you will find topics here for tools your current session doesn't show. If you're missing one, try opening a session against another server: the list is recomputed on every connection.

Keywords: tools, missing, not shown, navigator, availability, engine, session, hidden, Go

Collapse the groups you don't use and type in the field at the top to find a tool by name.

The Tools sidebar groups all of Calíope's tools by theme. Two things make it shorter.

Collapse a group: click its header. The chevron turns and the group's rows disappear; next to the name you'll see how many tools it is hiding, so nothing gets lost without a trace. Click again to expand it. What you collapse is remembered when you close the app, and it travels to your other Mac, iPad or iPhone if you have iCloud sync on.

Filter: the field at the top of the sidebar leaves only the tools that match what you type. It searches the tool's name, its full catalogue name and the sentence that says what it does, plus the name of its group — so typing the name of a group shows that group whole. Accents don't matter: replication finds Replicación.

While you are filtering, every group with matches is drawn open, even the ones you had collapsed. Nothing you find can stay hidden inside a closed group. Your collapsed groups are not touched: clear the field and everything goes back exactly as it was.

Press Esc or the × to clear the field. The filter is not remembered when you close the app — a sidebar that opens half empty for a reason you don't recall is worse than typing three letters again.

Keywords: sidebar, tools, filter, search, groups, collapse, expand

What works without connecting to any server, and what doesn't.

Calíope includes an offline Workspace accessible even when no server is connected. It is useful for drafting queries and organizing your snippets without needing a connection.

How to access:

From the Connection Manager, without connecting to any server. Where the button is depends on how much room there is: on a wide screen — the Mac and the iPad — it is on the welcome screen, next to “Create profile”; on a narrow one — the iPhone, and the iPad in a split window — that screen is not drawn at all, so it lives in the bottom bar, with the terminal icon.

Tools available in offline mode:
- SQL Editor — write and save SQL, use history and snippets. Queries cannot be executed against a server.
- Snippets — create, edit, and copy your code snippets.
- SQLite Editor — open a .sqlite file from disk and work on all of it: no server needed, because the file is the database.
- DuckDB Editor — open a .duckdb file —or a CSV, JSON or Parquet file in an in-memory database— and query it on the device itself, without a server.
- File Previewer — look at CSV, JSON, Markdown and the rest without leaving the app.
- Errors — the log is local, and you need to be able to read it precisely when you can't connect.
- Reports — you can view, edit and export results you already had; running one does need a server, and the view says so.

Offline mode banner: a golden strip at the top of the workspace indicates you are in offline mode.

To connect to a server from the offline workspace: on the Mac, click Connect server in the window toolbar, which opens the Connection Manager in its own window; on iPad, iPhone and Apple Vision Pro, tap Connect in the top bar, which opens it as a sheet. Either way the editor content is kept. The offline strip only tells you: it has no button.

Keywords: offline, offline mode, no server, offline editor, offline workspace, editor without connection, snippets

Displays the result, timing, and progress of ongoing operations.

The status bar appears at the bottom of the Workspace and the SQL editor. It reflects the state of the last executed operation.

Information displayed:
- Result message — descriptive text of the last operation (rows affected, execution time, error).
- Progress — progress bar or loading animation while a query or task is running.
- Percentage — for long operations (such as backups or restores) it shows numeric progress.

Copy the message:

macOS: double-click on the status bar text area to copy the full message to the clipboard. Useful for copying error messages without having to select them manually.

iPad: the same double-tap gesture copies the message.

The status bar is always visible and cannot be hidden.

Keywords: status bar, progress, message, copy message, error, execution time, double click

Reorder the buttons on the editor and results toolbars.

Where it is: SQL Editor › Customize toolbar

The SQL Editor has two toolbars of its own, each customized separately:

- Editor toolbar — above the text area: run, format, comment, history, schema panel…
- Results toolbar — above the grid: export, chart, column profiler, filters…

Opening the customizer
Click the ⋮≡ button (slider.horizontal.3 icon) at the start of the toolbar you want to adjust.

What you can do
- Reorder — drag each group of buttons where you want it, or use Move up and Move down from its context menu.
- Reset — restores that toolbar's original layout.

Both toolbars scroll horizontally, so no button is ever out of reach however narrow the window is.

For the Workspace tool launcher, see Customize the main bar.

Keywords: editor toolbar, results toolbar, customize, reorder, hide buttons, drag, sql editor

Reorder the buttons of the Workspace's main toolbar to put your favorite tools first.

Where it is: Workspace › Customize the main toolbar

The navigation sidebar gathers every workspace tool into groups by theme —development and querying, design and structure, diagnostics and performance, server administration…—. The factory layout is only a starting point: the groups, their order and what goes in each one are changed here.

How to open the customizer
- At the bottom of the navigation sidebar, next to the performance indicator, you will find the customization button ⋮≡ (slider.horizontal.3 icon).
- Click it to open the customization screen.

What you can do
The customizer offers a hierarchical and fully dynamic control split into two tabs:
- "Reorder Groups" Tab — Drag and drop entire sections to change the category layout, rename them, or even add your own custom groups.
- "Reorder Elements" Tab — Drag and drop individual tools within each group, or tap Move to... to dynamically move any tool to another section.
- Reset — The Reset button restores the native default layout and groups in a single tap.

Persistence and Self-Healing
Your layout is safely stored in UserDefaults (under the key caliope_sidebar_config_macos or caliope_sidebar_config_ipad). If Calíope introduces a new tool in a future update, it will automatically register within its default category without disturbing your personalized order.

Keywords: main toolbar, quick access, nav strip, customize, reorder, buttons, drag, overflow

Work with several servers at once without losing each one's context.

Where it is: Server menu › Add server

Calíope keeps independent sessions for every server you connect to. Each session has its own tabs, its own active database and its own query history.

Open another session
- Open the server menu —in the window toolbar on macOS, to the left of the tab bar on iPad— and press Add server. The Connection Manager opens: pick a profile and press Connect. The sessions you already had stay open.

Switch between sessions
- In the same menu, press the server you want to go to. Each session shows the profile name and a colored dot with its status.
- The server menu is not in the menu bar: it lives in the window, because each window can be looking at a different session.

Per-session state
- Each session remembers its active database, its open tabs and its query history.
- The SSH tunnel and encryption are set up once per session; switching sessions does not reconnect.
- The widget follows the profile pinned in Settings › Widget, whichever session is in front.

Close a session
- Disconnect, in the server menu or in the File menu (⌘⇧D), closes the active session, and its SSH tunnel if it has one.
- Passwords stay in the Keychain: they are not asked for again when you reconnect, unless you turned on biometrics.

Keywords: sessions, multi-session, multiple servers, simultaneous, switch session, server selector, add session, session manager, ⌘⌥N, disconnect

How to open the full help index on each platform.

Where it is: Help › Calíope Help

Calíope's help is available as a dedicated window or panel with an index, search, and section navigation. It opens differently per platform but shows the same content.

macOS: menu Help › Calíope Help or shortcut ⌘?. The help window stays floating and can remain open while you use the rest of the app.

iPad: menu Help › Calíope Help or shortcut ⌘? if you have an external keyboard connected. Help appears as a sheet; close it with the Close button in the upper-right corner or swipe down.

Contextual help (?): every view in the app has a ? button in its top bar that opens the related topic directly. It's the fastest way when you already know which tool you're looking for.

On the web: the same Help is published at https://caliope.org/help/, in the five languages. From there, with “I have Calíope installed” switched on, every topic has an “Open in Calíope” button that opens it in the app; a topic's link has the form caliope://help/<identifier>.

Apple Vision Pro: Help is the same sheet as on iPad, but a visionOS sheet is not closed by swiping it down: close it with Close (or Done, if you opened it from a “?” or from an error).

Keywords: help, help center, index, search topic, help menu, ⌘?, documentation, cmd?

Filter topics by engine, jump from a topic to its tool and send an SQL example to the editor.

The All engines menu in the index header keeps the topics of one engine and those that apply to all. An engine also brings in what belongs to its family: filtering by Aurora brings MySQL’s topics. The filter is remembered between openings and removed with Clear filter.

In the header of a topic with a location, Go closes Help and opens that tool or Settings.

In each SQL block of the DBA Handbook, Open in editor loads the example into the SQL Editor of the open session; outside the Mac it also closes Help.

Keywords: help, filter, engine, go, example, SQL, editor

With a narrow window, the tools go in a bar at the bottom: the first four of your order, and the rest in More.

When the window is narrow, the sidebar is not drawn and the tools move to a bar at the bottom. The first four of the order you choose in the customizer go there, and the rest in More. Changing the order in the customizer changes which ones you see.

On the Mac this bar does not exist, and on Apple Vision Pro the navigator goes in its ornament.

Keywords: bottom bar, tools, more, narrow screen, customize

If the session’s connection drops, Connection lost appears: you can go back to the connection manager or leave the tabs as they were.

If the session’s connection drops, the Connection lost alert appears.

Return to home disconnects the session and goes back to the connection manager. Cancel closes the alert and leaves the tabs as they were.

Keywords: connection lost, disconnect, session, return