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.
Visualize the relationships between tables in a database.
Where it is: Workspace › Tools › ER
Open the ER Diagram from the workspace navigation bar. Select the database in the top selector and Calíope will load the tables with their columns and existing foreign key relationships.
The diagram displays tables as nodes with columns and data types. Lines between tables represent the foreign keys detected on the server.
SQL Server
In SQL Server each schema is its own entry in the selector (demo.dbo, demo.rrhh). To see a foreign key that crosses schemas, add the other one with + DB: the line between the two is drawn in amber, as between two databases.
Keywords: ER, entity relationship, diagram, FK, foreign key, relationships, ERD
Zooming in and out — on macOS, the mouse wheel, a two-finger pinch on the trackpad, or the toolbar buttons; on iPad, the pinch or those same buttons. The percentage between the toolbar's − and + shows the current scale, and the shortcuts are ⌘−, ⌘+ and ⌘0. The limits are the same on all three: 18 % to 400 %, and the button dims once you reach either end.
Panning the canvas — drag over an empty area, on all three. Over a node, dragging moves the table instead.
Getting the whole diagram back — the Fit to window button (⌘0) frames every table. The diagram also re-fits itself when it opens and when the window is resized.
The Auto layout button rearranges the nodes to minimize overlaps.
Keywords: zoom, pan, scroll, zoom in, zoom out, canvas, navigate
Draw a new foreign key relationship between two tables.
Where it is: ER Diagram › right-click › Create FK relationship
Open the context menu on a table — right-click on macOS, press and hold on iPad — and select New FK relation…. A dialog opens to choose the source table and column, and the target table and column. When confirmed, Calíope executes the ALTER TABLE … ADD FOREIGN KEY on the server.
On macOS only, in addition: hold ⌃ (Control) and drag from one table to the target one; a rubber-band line follows the gesture and releasing opens that same dialog. On iPad the gesture does not exist, and the foreign key is created from the context menu.
Keywords: FK, foreign key, create relationship, ALTER TABLE, referential integrity
Keep the arrangement you gave the diagram, one per database.
Where it is: ER Diagram › Save layout
Click Save layout in the ER Diagram toolbar. Where you dragged each table is stored per database, so every diagram keeps its own arrangement.
The next time you open the diagram for that database, the tables come back where you left them. A table with no saved position — the ones of a second database you have just added with + DB, or one created since — is laid out on a grid beside the rest, never on top of them.
In the ER Diagram toolbar, the Export button offers two formats: PNG (an image, ready to paste into a document or a chat) and PDF (ready for printing or presentation). Each one offers three sizes, and the file is saved to the location you choose using the system dialog.
The same formats are in the canvas context menu, and on macOS the diagram can also be printed with ⌘P.
Inspect the full structure of a table directly from the diagram.
Where it is: ER Diagram › right-click › Edit table structure
Open the context menu on a table node in the diagram — right-click on macOS, press and hold on iPad — and select Edit table structure. A panel opens showing the complete CREATE TABLE statement for the selected table.
Compare two databases on the same server — tables, views, routines, triggers and events — and generate the migration script.
Where it is: Workspace › Tools › Schema Diff
The Schema Diff tool analyzes two databases on the same server and shows exactly what changed across tables, views, procedures, functions and triggers.
MySQLMariaDBAurora
On MySQL and MariaDB it also compares events.
SQL Server
On SQL Server each side is a schema of a database (demo.dbo), and the two may live in different databases of the same server.
PostgreSQL
On PostgreSQL each side is a schema of the connected database (demo, ventas).
Opening Schema Diff:
Click Schema Diff (opposing arrows icon) in the sidebar. It opens in a new tab.
Basic use:
1. Pick the Source and the Target on the top bar. The script changes the source until it matches the target: what only the target has is created in the source, and what only the source has is dropped.
2. Click Compare. Calíope reads each object's definition on both sides, as the server itself writes it.
3. Turn on the Changes only toggle to hide what matches.
4. The report is grouped by object type. Expand any row: a modified table shows, change by change, the definition it has and the one it will get; a modified view or routine shows both full definitions side by side; a new or dropped object shows its DDL.
5. Click Copy SQL for the whole script, or a row's copy button for that object alone.
6. Run it in the SQL Editor with Run Script. With Safe Mode on, it stops the script before it reaches the server. Compare again afterwards: the two sides should come out identical.
MySQLMariaDBAurora
The definitions are each object's SHOW CREATE …, and the editor understands the DELIMITER blocks that routines and triggers come in.
SQL Server
The definitions come from the catalog (sys.sql_modules for views, routines and triggers). Each view, routine and trigger goes in its own EXEC … sp_executesql, because T-SQL wants it alone in its batch, so the script runs without GO lines.
PostgreSQL
The definitions are the ones the server writes with pg_get_viewdef, pg_get_functiondef and pg_get_triggerdef.
What it generates for tables:
MySQLMariaDBAurora
- A full CREATE TABLE IF NOT EXISTS for those missing from the source, with columns, indexes and options.
- DROP TABLE IF EXISTS for the ones left over.
- ALTER TABLE with ADD/DROP/MODIFY COLUMN, preserving type, nullability, default value, comment, character set and generated-column expression.
- Added and dropped primary keys, indexes and CHECK constraints, plus table option changes (ENGINE, DEFAULT CHARSET, COLLATE, ROW_FORMAT, COMMENT).
SQL Server
- IF OBJECT_ID(…) IS NULL CREATE TABLE for those missing from the source, with columns, keys and constraints, and a CREATE INDEX for each index.
- DROP TABLE IF EXISTS for the ones left over.
- ALTER TABLE with ADD, ALTER COLUMN and DROP COLUMN; before dropping a column, the script drops the default constraint that hangs from it.
- Added and dropped primary keys, indexes and CHECK constraints.
PostgreSQL
- CREATE TABLE IF NOT EXISTS for those missing from the source, with columns and constraints, and a CREATE INDEX for each index.
- DROP TABLE IF EXISTS for the ones left over.
- ALTER TABLE with ADD COLUMN, DROP COLUMN and ALTER COLUMN … TYPE, SET/DROP NOT NULL and SET/DROP DEFAULT.
- Added and dropped primary keys, indexes and CHECK constraints, and the table comment (COMMENT ON TABLE).
What it generates for everything else:
A view or a routine cannot be patched piecemeal: if its definition differs, the script rebuilds it from the target, rewriting the references to the source schema so it points at the right place.
MySQLMariaDBAurora
It rebuilds with DROP + CREATE.
SQL Server
It rebuilds with CREATE OR ALTER, which views, procedures, functions and triggers all accept.
PostgreSQL
It rebuilds with CREATE OR REPLACE; a trigger or a materialized view, which do not have it, are dropped and created again.
Script order:
Tables first; then foreign keys in their own block, because when several tables are created alphabetical order does not respect dependencies; then the remaining objects by type, each type ordered by dependencies — a view built on another is emitted after it.
MySQLMariaDBAuroraSQL Server
Before the first object that is not a table, the script sets the active database with a USE.
PostgreSQL
Before the tables come the schema's own types, which their columns are declared with.
Ignored on purpose:
MySQLMariaDBAurora
The AUTO_INCREMENT counter, which advances with every insert and never matches between two copies.
SQL ServerPostgreSQL
The current value of an identity column, which advances with every insert and never matches between two copies.
What it does not cover:
Columns of an existing table are not reordered, and a renamed column reads as a drop plus an add. Views, routines and triggers are compared textually, so a mere formatting change counts as a difference.
MySQLMariaDBAurora
A partitioning change is detected and noted as a warning but never turned into SQL: repartitioning rewrites the whole table. A DEFINER change also counts as a difference, and on MariaDB a trigger's DDL is the literal text it was written with. An event with a different start time also differs, because that time is part of its definition.
PostgreSQL
Types of their own — ENUM, domains, composite types — are compared like a view, in their own Types group. The script creates the missing ones before the tables that use them and drops the ones only the source has at the very end. An ENUM that only gained labels at the end is updated with ALTER TYPE … ADD VALUE; any other change to a type stays in the script as a note to make by hand, because rebuilding a type in use means rewriting every column that uses it. The types an extension creates, such as PostGIS's, are left out: its CREATE EXTENSION brings them.
Always review the script before running it in production.
Typical use case:
Before a deployment, compare production (source) against the development schema (target): the script brings production up to what development already has, without writing it by hand.
Available on macOS, iPad and iPhone.
Keywords: schema diff, compare, schema, alter table, migration, differences, ADD COLUMN, DROP COLUMN, MODIFY COLUMN, SHOW CREATE TABLE, CREATE TABLE, indexes, foreign keys, partitioning, changes only
Add a second database to the ER diagram canvas to visualize relationships across databases.
Where it is: ER Diagram › + DB
The ER Diagram can display tables from two databases simultaneously on the same canvas, including foreign keys that cross from one database to the other.
How to add a second database:
1. With the ER Diagram open, select the primary DB in the left selector of the toolbar.
2. Click the + DB button in the toolbar to add a second database.
3. Select the second DB in the new selector that appears.
4. The canvas updates automatically, showing the tables of both databases.
Color coding:
- Blue header — tables from the primary DB.
- Teal header — tables from the second DB.
- Orange arrows — foreign key relationships that cross from one database to the other.
- Regular arrows — relationships within the same database.
Requirement for cross-database relationships:
Foreign keys must be declared in information_schema. MySQL/MariaDB records FKs in information_schema.KEY_COLUMN_USAGE. If cross-database relationships do not appear, verify that the FKs exist formally on the server (not just as naming conventions).
Navigation and export:
All features of the standard ER diagram apply to the multi-database canvas: zoom, pan, auto-layout, save layout, export PNG/PDF, and view table DDL. See the ER Diagram topics for more details.
Available on macOS, iPad and iPhone.
Keywords: erd, multi-database, cross-database, relationships, second database, foreign key, diagram, multi-db, blue header, teal header, orange arrows