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.
Load tabular data from CSV, JSON, or Excel files directly into a table.
Where it is: Schema tree › right-click › Import data…
Calíope includes a three-step import wizard for loading data from external files.
How to access: Right-click (macOS) or long-press (iPad) on a table name in the schema tree and select Import data…. The wizard opens pre-configured with the selected database and table.
Step 1 — File:
Click Select file… and choose the file to import. The wizard automatically detects the format. Files larger than 64 MB (CSV, JSON or Excel) are rejected before being read: the wizard says so right there, with the file's size and the maximum. To import more, split the file into several.
Supported formats:
- CSV — with automatic delimiter detection (,, ;, tab). A quoted field can span several lines: the line breaks inside the quotes stay in the value.
- JSON — array of objects [{…}, {…}].
- Excel (.xlsx) — first sheet of a Microsoft Excel or Numbers workbook.
Step 2 — Columns:
The wizard displays the file's columns and a selector to map each one to the corresponding column in the target table. Unmapped columns are labeled Ignore and are not imported. Enable First row is header if the file has a title row.
Step 3 — Import:
Configure the import options:
- Insert mode — appears only when the engine offers more than one:
- Insert — inserts the rows as they are. A row whose primary key already exists fails with the server's message.
- Skip duplicates — inserts the new rows and leaves out those whose primary key already exists.
- Replace duplicates — if the primary key already exists, the file's row replaces the one in the table.
- Rows per batch — number of rows inserted in each INSERT statement. Options: 100, 500, or 1000. Larger batches are faster but consume more server memory.
MySQLMariaDBAurora
With MySQL and MariaDB all three modes are offered.
PostgreSQL
With PostgreSQL only Insert and Skip duplicates are offered: what Calíope can write there for a duplicate skips the row, it does not replace it, so Replace duplicates would promise something that does not happen.
SQL Server
With SQL Server only Insert is possible, so the selector is not drawn: a duplicate fails with the server's message.
The log panel displays the progress and result row by row.
Export selected databases and objects to a .sql or .sql.gz file without blocking the UI.
Where it is: Workspace › Tools › Backup
Open Backup from the workspace navigation bar. In the Backup tab, select the databases and objects to include using the tree on the left. Configure the options and choose the destination file. Click Create Backup.
Background processing:
The backup runs entirely off the main thread. The UI remains fully responsive while the engine dumps data. The log panel below shows per-object progress in real time.
Estimated time remaining (ETA):
Once the first object is processed, an estimated time counter appears next to the progress bar, calculated from the current dump rate.
Cancelling a backup:
Click Cancel at any time. The engine stops after the current operation completes and removes the partial file from disk.
macOS:Save to… chooses the file in the save panel; when it finishes, Show in Finder takes you to it. iPad: on completion, the Share file button appears to export the file to device storage or iCloud Drive.
Notification on completion:
If you minimize or switch apps during a long backup, Calíope sends a local notification when it finishes or if it fails. Requires notification permission (macOS: Notification Center; iPad: Settings › Notifications). Enable or disable this in Preferences › Notifications › Manual backup in background.
Choose which tables, views, routines, and users to include.
Where it is: Backup › Selection tree
The tree on the left shows each database with its object types: Tables, Views, Routines and Triggers, plus Events where the server has them. Everything starts selected when the tool opens. Select all and Deselect all mark or clear everything, and the quick links All, Only tables and Schema only select in bulk (Schema only also turns off Include data); or check and uncheck items one by one. The Server users section lets you include the server's user accounts and their privileges in the backup.
The tree also has a filter by name in its header and shows the estimated size next to each table. Each database checkbox selects or clears everything under it, and to its right you see how many objects are selected out of the total. The Server users section sits below the tree, not inside it: users belong to the server and hang from no database. A database created after opening the tool appears with Refresh database list in the tree's context menu.
SQL Server
Each entry of the tree is a database with one of its schemas (demo.dbo, demo.rrhh): the backup writes the database, the schema and its objects.
PostgreSQL
Each entry of the tree is a schema of the database you are connected to: the backup writes the schema, the extensions it uses and its objects. The objects an extension brings —PostGIS's functions, for instance— are not listed: on restore, the file creates the extension again.
Execute a .sql or .sql.gz file against the server to restore data.
Where it is: Backup › Restore tab
In the Restore tab, choose the file with Choose file…. Both .sql and .sql.gz (gzip-compressed) files are accepted; Calíope detects the format via the file's magic number rather than the extension, so renaming the file does not change the result.
Preview: press Preview to inspect the first ~200 lines before running. Useful to verify which databases and statements a dump contains before applying it.
Prior confirmation: pressing Restore shows a summary with the number of statements detected and the affected databases (read from the statements that select, create or drop them). If the script contains DROP statements, the summary warns that existing objects will be removed.
SQL Server
The file goes in batches separated by GO lines, and the restore cuts only at those lines: a procedure body with ; inside arrives whole.
PostgreSQL
The file is restored into the database you are connected to: its schemas are created there.
MySQLMariaDBAurora
A dump from mysqldump or mariadb-dump is restored as the command-line client would: its executable comments (/*!40101 … */) reach the server, and binary columns dumped raw, without --hex-blob, arrive byte for byte.
Cancellation: during restore you can press Cancel to stop after the current statement.
Errors: the restore runs in a single session and stops at the first error. The log names the statement that failed (the object and its database) with the server's message, and says at which statement it stopped.
macOS: the picker opens the standard Finder dialog. iPad: the picker uses the system document browser with access to iCloud Drive and compatible apps. A security-scoped bookmark is generated so the file can be re-read after closing the picker.
Requires an active connection: the button is disabled if no server is connected. An orange warning flags the state.
Configure the content, format, and compression of the generated backup file.
Where it is: Backup › Options section
In the Backup tab, the options section lets you adjust what the generated file includes:
- DROP before CREATE — adds DROP TABLE IF EXISTS (or DROP VIEW, DROP PROCEDURE, etc.) before each CREATE statement. Recommended for clean restores that overwrite existing objects.
- Include data — adds INSERT statements with the data from each selected table. Disable this to generate the schema only (structure without data).
- Include user passwords — appears when server users are included. Explicit opt-in, off by default. When off, the password —or its hash— is written as '***REDACTED***'. Turn it on only if you plan to restore the file on the same server and the destination folder is not synced to iCloud Drive, Dropbox or any other service.
- Include date in filename — adds the date and time to the file name; on macOS, to the name that Save to… suggests (e.g. backup_2026-06-05_14-30.sql).
- Include server users — the checkbox of the Server users section, below the tree: exports the accounts ticked there and their privileges with the statements that create them and their privileges.
- Compress output (.sql.gz) — applies gzip compression to the file as it is generated, without keeping the full SQL in memory. The resulting file is typically 70–85 % smaller than the equivalent .sql file. Compression uses Apple's Compression framework in real time.
MySQLMariaDBAurora
Server users are written as CREATE USER and GRANT.
SQL Server
Server users are the logins: each one is written as CREATE LOGIN … WITH PASSWORD = … HASHED, with its user, roles and permissions in each database. DROP before CREATE also drops, first, every object of each schema the file brings.
PostgreSQL
Server users are the roles: each one is written as CREATE ROLE, and the predefined pg_ roles only with their grants, because every server already has them. DROP before CREATE drops each schema whole (DROP SCHEMA … CASCADE) before creating it again.
macOS:Save to… chooses the file in the standard save panel. iPad: on completion, the Share file button lets you export the .sql or .sql.gz to any destination supported by the system file picker.
Keywords: backup options, DROP IF EXISTS, include data, include users, schema, structure, data, filename date, drop before create, compress, gzip, sql.gz, compression
Set up recurring backups (daily, weekly, weekdays, monthly or every N hours) with a system notification on completion.
Where it is: Workspace › Tools › Backup
Calíope can run backups automatically without manual intervention. To configure them, open the Backup panel from the Workspace sidebar.
How to set up a scheduled backup:
1. In the Scheduled tab of the Backup panel, click New.
2. Give it a name and choose the connection profile (or any active connection), the frequency (daily, weekly, Monday to Friday, monthly, every N hours, or on demand), the time, the destination folder and how many copies to keep.
3. The switch on its row turns it on and off.
A scheduled backup copies every database of its connection, with DROP before CREATE and the data, uncompressed. To back up only some databases, save a preset from the Backup tab and give it a frequency with its pencil button.
Behavior:
- When the app is open at the configured time, the backup runs in the background without blocking the UI.
- Upon completion, you will receive a system notification with the filename and its size.
- If the app was not open at the scheduled time, the backup is marked as pending: a banner says how many were missed, and Run now on its row launches it.
- Older backups are automatically deleted when the configured maximum number of copies is exceeded.
Destination folder selection:
Calíope runs in a strict sandbox (an App Store requirement). When you pick the folder with Choose folder…, a persistent permission is created for that specific path. If you later move or rename the folder, the app will warn you that it needs you to select it again. Editing the path by hand in the profile is not enough — always use Choose folder….
Performance:
Scheduled backups use the same streaming engine as manual ones: data is written directly to disk object by object, without buffering the full SQL in memory. This allows backing up databases of any size without risk of RAM exhaustion or app freezing.
Available on macOS, iPad and iPhone. Requires system notification permission.
Reuse a backup's parameters without scheduling it. Presets run on demand with one click.
Where it is: Backup › Scheduled tab
In addition to automatic backups (daily, weekly, weekdays, monthly, or every N hours), the Scheduled tab can hold manual templates: named configurations that run only when you press the Run button on their row.
How to create a manual template:
1. In the Backup tab, select what to back up and press Save as preset… next to Create Backup. The preset keeps the connection and the databases that hold the selected objects (whole databases), and is registered in the Scheduled tab with frequency "Manual — on demand". The folder is not carried over, because the file picked with Save to… gives no permission to write in its folder later: choose it with the pencil button (Choose folder…) before the first run. The options are those of every scheduled backup: DROP before CREATE and the data, uncompressed.
2. Alternatively, in Scheduled › New, choose the option No schedule (run on demand) in the frequency picker.
Visual differences of a manual preset:
- Indigo bolt.circle.fill icon (vs. green calendar.badge.checkmark for active scheduled ones).
- Primary Run button always visible on the row.
- No active/inactive toggle and no "next run" (do not apply).
- No missedRuns accumulation (do not participate in the automatic cycle).
Available frequencies for automatic backups:
- Daily at a fixed hour.
- Weekly on a specific day of the week.
- Mon-Fri (weekdays) Monday to Friday.
- Monthly on a specific day (1–28) of the month.
- Every N hours counted since the last run.
- Manual (on demand) — no automatic schedule.
Run history: the clock.arrow.circlepath button on each row (View history) opens the runs of that backup: successes, failures, cancelled and skipped. With no runs yet, it says so.
Keywords: preset, template, manual, on demand, scheduled, frequency, monthly, weekdays, every N hours, history, run history