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.
Load tabular data from CSV, JSON, or Excel files directly into a MySQL 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.
Supported formats:
- CSV — with automatic delimiter detection (,, ;, tab).
- 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:
- INSERT — inserts rows normally. Fails if a primary key conflict exists.
- INSERT IGNORE — inserts new rows and silently ignores those that already exist (PK duplicates).
- REPLACE — if a PK conflict exists, deletes the existing row and inserts the new one.
- 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.
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 Generate 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: the file is saved to the path chosen in the Finder panel. 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, Triggers, and Events. Use the quick buttons All, None, and Tables only to select in bulk, or check/uncheck items individually. The Users section lets you include MySQL 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 Users section sits below the tree, not inside it: users belong to the server and hang from no database.
Execute a .sql or .sql.gz file against the server to restore data.
Where it is: Backup › Restore tab
In the Restore tab, select the file using the unified picker. 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 (extracted from USE, CREATE DATABASE, and DROP DATABASE). If the script contains DROP statements, the confirmation button is marked in red.
Cancellation: during restore you can press Cancel to stop after the current statement.
Errors: the log panel shows each error with the first line of the failing statement so it can be located in the original dump.
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 — explicit opt-in, off by default. When off, CREATE USER / GRANT statements are written with IDENTIFIED BY '***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 — appends the current date and time to the output filename (e.g. backup_2025-06-05_14-30.sql).
- Include users — exports MySQL user accounts and their privileges using CREATE USER and GRANT statements.
- 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.
macOS: the file is saved using the standard Finder dialog. 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 daily or weekly backups 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 section within the Backup panel, click Add schedule.
2. Choose the database to back up, the frequency (daily or weekly), the execution time, and the destination folder.
3. Enable the schedule's toggle to activate it.
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 will be marked as pending and will run the next time the app is opened.
- 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 Browse, 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 the Browse button.
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. From the Backup tab, after configuring destination and options, press Save as preset… next to the Create backup button. The template is registered in the Scheduled tab with frequency "Manual — on demand".
2. Alternatively, in Scheduled › Add, 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: each scheduled backup stores the last 10 runs (successes, failures, cancelled, and skipped). The clock.arrow.circlepath icon on the row opens the sheet with the table.
Keywords: preset, template, manual, on demand, scheduled, frequency, monthly, weekdays, every N hours, history, run history