Sketch

Sketch is how Alcuin treats a database that holds nothing of anyone’s yet. While a database is in Sketch, structure changes apply as you make them instead of waiting for review, and each one can be undone. When the database starts to hold real data, Sketch ends on its own and Alcuin goes back to reviewing every change before it runs.

Every other database is Live. Live is what the rest of these docs describe: changes are staged, you choose Review SQL, and nothing runs until you commit (How Alcuin keeps your data safe).

Which databases can be in Sketch

Only databases on a Local or Development connection. A Staging or Production database is never in Sketch, and a connection moved to Staging or Production leaves it at once.

A database starts in Sketch in two ways:

• Alcuin created it. A database made with New database… starts in Sketch.
• You put it there. Run Sketch this database from the command palette. Alcuin first checks that the database is empty of real data. If it isn’t, it says why, for example public.orders holds 1,204 rows, so this database is already someone's. or Another application is connected to this database, so it cannot be sketched.

Once it is in, Alcuin says so:

In Sketch: nothing here is anyone’s data yet. It leaves on its own when that changes.

The top bar shows a Sketch chip. Its menu says how many changes were made so far, and holds Hand off…, Promote…, Show changes, Restore to checkpoint… and This is real now.

The Sketch chip and its menu.

When Sketch ends

A database leaves Sketch on its own when:

• a table holds rows that Alcuin’s seed didn’t put there, or
• another application connects to it (Alcuin’s own sessions and agents don’t count), or
• its connection is moved to Staging or Production, or
• Alcuin can no longer read what it holds.

Alcuin checks when the database opens, when the window comes back to the front, every 30 seconds while the window is in front, and again right before it applies any change. The message names the reason and ends From here, changes to <database> are reviewed before they run.

To leave on purpose, run This is real now. For 60 seconds afterward, Undo puts the database back in Sketch, if it is still empty.

Settings, under Stages, lists each saved connection as Sketch or Live. The list is for reading; the commands above are how a database moves between the two.

How changes behave in Sketch

	Live	Sketch
A structure change (add a column, drop an index…)	Staged. Runs when you review and commit it	Applies as soon as it is complete
Review SQL and the staged-changes bar	Shown	Hidden. Each change shows a toast with its SQL and Undo
Undo	Discard before you commit	Undo the last change (⌘Z / Ctrl+Z) runs the change’s reverse; Redo the change undone last (⌘⇧Z / Ctrl+Shift+Z) runs it again
Edits to rows	Staged and committed	Still staged and committed. Rows you add yourself end Sketch, since they are real data
Queries you run in the query editor	Checked by the Safety rules	The same: Sketch changes nothing about them

Changes come off in the order they were made: undo always takes back the newest one first. The list of changes made in Sketch is in the Migrations view, and Show Sketch changes opens it.

In Sketch a change applies at once, with its SQL and Undo, and ⌘Z takes it back.

When it asks, and when it doesn’t

In Sketch, Alcuin does not ask before a destructive structure change that it can undo exactly. Dropping a column, a table or an index applies with no prompt, because Undo can put it back.

Everything else still asks as your Safety rules say:

• A change with no exact undo. Alcuin first tries to take a checkpoint, so that a restore can undo it. When it can’t, the change waits with … waits for a yes and the choices Apply it and Discard. Applying asks Apply this without an exact undo? first.
• Grants and other changes Alcuin has no reverse for. They are staged for review, as on Live.
• Statements you run in the query editor. Your rules apply as usual, Ask before: destructive statements included.
• Every other kind of ask you turned on, such as Ask before: structure changes or Ask before: every write. Sketch relaxes only destructive statements.

Checkpoints

A checkpoint is a copy of the whole database on the same server, kept as a database of its own named <database>__alcuin_<n>. Restoring one puts the database back exactly as it was when the copy was taken. Checkpoints work on Local and Development connections, in Sketch or not.

• Take one: Checkpoint…, or ⌘⇧S / Ctrl+Shift+S in Sketch. Name it after the change it follows. A named checkpoint is kept until you delete it.
• Automatic ones: Alcuin takes a checkpoint after it creates a database, after you seed it, when a sketched database first has tables, and before a change only a checkpoint can undo. Settings, under Checkpoints, sets how many automatic ones are kept: 1, 3, 5 (the default), 10 or 20. Past that, the oldest goes.
• Go back: Show checkpoints, or Restore to checkpoint… in Sketch’s menu, lists them with Restore… and Delete…. Alcuin shows what differs before it restores. In Sketch, what is there now is kept as a checkpoint of its own, so a restore can be undone too. On Live, it asks you to confirm first.

What a checkpoint needs:

• Your user may create databases (CREATEDB) and owns the database.
• The connection is not read-only. Unlock it first.
• Nothing else is connected to the database while it is copied or restored. Alcuin’s own tabs pause and reconnect. On a Local connection, Alcuin offers to end the other sessions, and asks first.
• Room on the server’s disk for a full copy. On Postgres 18, on a file system that can clone files (APFS, XFS, Btrfs), the copy is nearly instant and takes almost no space. On older versions every file is copied, and Alcuin says how long it expects that to take.

A checkpoint is not a backup: it lives on the same server as the database.

Sketch and migrations

What you change in Sketch is what your app’s next migration should hold. Hand off…, in the Sketch chip’s menu and in the message when Sketch ends, opens Save as migration… with those changes, for the migration tool your project folder uses. Migrations walks through it.

What success looks like

You add, rename and drop columns on a new database and each change appears at once, with a toast you can undo. When you are happy, you hand the changes off as a migration, or run This is real now, and from then on every change waits for Review SQL.