Snapshot Before a Schema Change

Role: Developer · Screen: Data timeline → Take Snapshot, then Restore if you need to roll back · Time: a few minutes before the schema change

This page is the clicks. For the story, read Take a Snapshot Before Schema Changes. For a coding agent on your laptop, see Coding agent snapshot.

Restore lists the latest snapshot per data item and tag combination. Use a distinct tag value for this baseline (for example work=baseline), not only date. If the next backup reuses the same tags, Restore will hide this version behind the newer one.

Before you start

You have this database as a data item on Data. If not, follow Take a tagged snapshot (Quick Backup Wizard if the list is empty).
The agent is ONLINE.
You are about to change schema — a migration script, or Hibernate ddl-auto=update on the next app start. Take the snapshot before that happens.

Steps

1

Take a baseline snapshot

Open Data, open this database’s data item, click the Take Snapshot card, pick the backup flow, click Take Snapshot.

On Execute Flow, under Execution Tags, set a pair you will not reuse for later “latest” backups of the same work, for example:

work=baseline — schema before this change
Keep a stable tag such as app=quemsi if you filter that way too

Add a description that names the migration (ticket, branch, or script). Click Execute Flow and wait for success.

Full Take Snapshot clicks: Take a tagged snapshot.

2

Confirm the version

You are already on that data item’s timeline after you go back. Check the new version has work=baseline (and your other tags). That is the card Restore will show for those filters until you take another snapshot with the same combination.

3

Run the migration

Apply the schema change in your usual tool: a migration runner, or start the app if Hibernate auto-DDL will update the schema. Quemsi is not the migration runner.

4

If it fails, restore the baseline

Open Data → Restore, filter to work=baseline (and app if you used it), pick the card, choose the database you changed, and confirm Restore and overwrite.

Full restore clicks: Restore a tagged snapshot.

Need both the old and the new state later?

After a successful migration, take another snapshot with a different value, for example work=after-auth-v2. Park-and-switch uses the same idea: Park work and switch.

Not this page

Recurring nightly backups — Schedule a recurring backup. Give those a tag such as use-case=nightly, not work=baseline, so they do not replace the baseline card on Restore.
Urgent interrupt while a long feature is in progress — Park work and switch.
Also from a coding agent (CLI + Cursor hook): Coding agent snapshot.
Also from CI: Snapshot before deploy.