feat(cli): Back up the database on upgrade and add `cli upgrade undo` by sentry-junior[bot] · Pull Request #1631 · getsentry/toolkit

sentry-junior · 2026-10-23T13:48:25Z

Closes #1623. Builds on #1612 (merged), using its hook that runs after the new binary is downloaded and before it runs cli setup.

sentry cli upgrade now copies cli.db to backups/cli-<from>_to_<to>.db under the config directory before another version runs setup. The file name is the record: the newest backup is the last upgrade, so there is no separate manifest. sentry cli upgrade undo reinstalls <from> and puts its own database back. This is the backup-and-restore approach BYK suggested on #1612, so newer CLIs don't need to rewrite their schema for older ones.

Following BYK's answers on #1623:

Logins (merge when possible, warn at least): the restored database gets the current accounts rows, so logins and refreshed tokens made since the backup are kept. Accounts removed since then (logged out) stay removed. When the backup has no accounts table (before schema v18), or the rows can't be copied, the result warns that the user may need to sentry auth login. The result also warns that other changes since the backup, like defaults, are undone.
Retention (one per version): a version's backup replaces its earlier one. I also capped them at the five most recent, because nightly users would otherwise collect one per nightly. The backup an undo would restore is the newest, so it is never pruned.
Other install methods: undo only covers version changes made by sentry cli upgrade and says so. Downgrades through npm or Homebrew still rely on fix(cli): Keep the local database usable across CLI downgrades #1612's newer-database detection. On a Homebrew install, which can't install an earlier version, undo points to sentry cli upgrade undo --method curl.
Secrets: backups are 0600 in a 0700 directory, like cli.db.

How it works

The backup runs only after the download succeeds and before any CLI crashes with "ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint" after switching from nightly back to stable #1611 hand-off, so a failed download changes nothing and the backup keeps the logins. Reinstalling the same version doesn't back up, so it can't overwrite the record of the upgrade that led there.
Backups use VACUUM INTO, which takes a consistent copy while other CLI processes use the database. File operations use node:fs/promises.
Undo finds its backup by scanning backups/: the newest file by mtime is the last upgrade, and it only counts if <to> is the running version. _ isn't valid in semver, so it separates the two versions unambiguously.
Undo installs the earlier version on its own channel and doesn't save a channel change to the current database, because the restored database already has its own.
Undo also backs up the current database first, so an undo can be undone.
The restore checkpoints the WAL and closes cli.db, then swaps in the copy. For the rest of the run, the upgrading CLI uses a throwaway in-memory database (detachDatabase), so it can't migrate the restored file forward again. If the swap fails, the current database is left in place and the CLI crashes with "ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint" after switching from nightly back to stable #1611 hand-off runs as it would without undo.
Undo fails with a clear message when there is no backup, or the newest backup wasn't made upgrading to this version.

Limitation: a backup only exists once the version doing the upgrade includes this change, so undo can't return to 0.47.0 or other older releases.

Tests: test/lib/db/backup.test.ts covers backup naming and pruning, the undo checks, restoring with logins kept, older-format backups, and that the restored file isn't touched afterwards, with a full round trip on both the node:sqlite and WASM drivers. upgrade.test.ts derives its versions from CLI_VERSION with semver and covers the backup existing before setup runs, a full cli upgrade undo, undo refusing when the last upgrade went to another version, the Homebrew message, and the nothing-to-undo error.

via BYK.

--

View Junior Session [Sentry]

vercel · 2026-10-23T13:48:33Z

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-local	Skipped		Oct 27, 2026 10:02pm UTC

cursor

Stale Bugbot comment from a previous run.

Before `sentry cli upgrade` hands the local database to another version, it now copies `cli.db` to `backups/cli-<version>.db` under the config directory and records which version it moved from. `sentry cli upgrade undo` reinstalls that version and puts its own database back, so newer CLIs don't need to rewrite their schema for older ones. - The restored database keeps the current logins when the older version stores them in `accounts`; otherwise the command warns that the user may need to log in again. - One backup per version, at most five, never pruning the one an undo would restore. Backups are 0600 in a 0700 directory, like `cli.db`. - The upgrading process detaches from `cli.db` after restoring it, so it can't migrate the older version's database again. Closes #1623. Co-Authored-By: BYK <burak.kaya@sentry.io>

- Restoring a backup after logging out of every account brought the backup's logins back. The restored database now ends up with no accounts (or an empty pre-v18 `auth` row) in that case. - `sentry cli upgrade undo` on a Homebrew install failed with the generic "Homebrew does not support installing a specific version" error. It now says undo can't go through Homebrew and points to `sentry cli upgrade undo --method curl`. - Commit the regenerated skill reference for the docs fragment change. Co-Authored-By: BYK <burak.kaya@sentry.io>

Each backup is now cli-<from>_to_<to>.db and the newest one is the last upgrade, so undo reads the backup directory instead of a manifest. Backup and restore use async fs calls, the undo argument constant is MAGIC_VERSION_FOR_UNDO, and the upgrade tests derive their versions from CLI_VERSION with semver. Co-Authored-By: BYK <burak.kaya@sentry.io>

cursor

Stale Bugbot comment from a previous run.

The new binary installs itself during setup, so a failed setup leaves this version installed. The backup made for that upgrade then hid the earlier one from undo, and a failed undo left the older version's database in place. Both are now reverted, and this process uses its own database again.

cursor

Stale Bugbot comment from a previous run.

A #1611 hand-off is redone after a failed setup, so reinstating this version's database first had it wiped, and discarding the backup threw away the only intact copy. A failed setup that needed the hand-off now keeps the backup and leaves a restored database in place.

cursor

Stale Bugbot comment from a previous run.

…nd-off A restore makes the #1611 hand-off unnecessary, so a failed undo to a CLI below 0.48.0 can put this version's database back and skip the hand-off like any other failed undo.

BYK

What about that Warden issue raised?

Warden: a failed curl downgrade to a pre-0.48 CLI kept the handed-off database, with its logins deleted, while this version stayed installed. The backup is now moved back into place and the hand-off isn't redone. Without a backup, the hand-off is still redone as before. listBackups also scans the directory with opendir, per review.

sentry-junior · 2026-10-27T21:21:48Z

@BYK On the Warden finding (a failed curl downgrade to a pre-0.48 CLI kept the handed-off cli.db, with its logins deleted, while this version stayed installed): fixed in 07cb5e6. When a --install setup fails, the backup taken just before it is moved back into place, and the hand-off isn't redone. The #1612 redo after a failed setup still runs when there is no backup to put back.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 07cb5e6. Configure here.}

Some filesystems (NFS, some FUSE and bind mounts) don't report a type on directory entries, so Dirent.isFile() skipped real backups. Match the name first, then use the stat result to check the type.

…his database Undo passed the target's artifact channel to setup, which records it and overwrote the release channel stored in the restored database. Setup now gets no --channel for an undo. An undo that installs the binary through setup now stops when this version's database can't be backed up: a failed setup could otherwise not put it back, leaving this version with the restored database.

github-actions Bot added the risk: medium PR risk score: medium label Oct 23, 2026

cursor Bot reviewed Oct 23, 2026

View reviewed changes

Comment thread packages/cli/src/lib/db/backup.ts

Comment thread packages/cli/src/commands/cli/upgrade.ts

vercel Bot temporarily deployed to Preview October 23, 2026 13:59 Inactive

BYK requested changes Oct 27, 2026

View reviewed changes

sentry-junior Bot force-pushed the fix/cli-db-newer-schema-downgrade branch from 488037c to d814a7d Compare October 27, 2026 17:20

sentry-junior Bot force-pushed the feat/cli-upgrade-undo branch from a97653a to db9651d Compare October 27, 2026 17:34

vercel Bot temporarily deployed to Preview October 27, 2026 17:34 Inactive

Base automatically changed from fix/cli-db-newer-schema-downgrade to main October 27, 2026 17:37

sentry-junior Bot and others added 3 commits October 27, 2026 19:25

sentry-junior Bot force-pushed the feat/cli-upgrade-undo branch from db9651d to 7f946ee Compare October 27, 2026 19:27

vercel Bot temporarily deployed to Preview October 27, 2026 19:28 Inactive

cursor Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/commands/cli/upgrade.ts

vercel Bot temporarily deployed to Preview October 27, 2026 19:43 Inactive

cursor Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/commands/cli/upgrade.ts

Comment thread packages/cli/src/commands/cli/upgrade.ts

vercel Bot temporarily deployed to Preview October 27, 2026 19:52 Inactive

cursor Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/commands/cli/upgrade.ts Outdated

fix(cli): Reinstate the database after a failed undo that needed a ha…

4483a90

…nd-off A restore makes the #1611 hand-off unnecessary, so a failed undo to a CLI below 0.48.0 can put this version's database back and skip the hand-off like any other failed undo.

vercel Bot temporarily deployed to Preview October 27, 2026 20:00 Inactive

BYK requested changes Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/lib/db/backup.ts Outdated

Comment thread packages/cli/src/lib/db/backup.ts Outdated

vercel Bot temporarily deployed to Preview October 27, 2026 21:21 Inactive

cursor Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/lib/db/backup.ts Outdated

fix(cli): Check backup file types with stat

db946be

Some filesystems (NFS, some FUSE and bind mounts) don't report a type on directory entries, so Dirent.isFile() skipped real backups. Match the name first, then use the stat result to check the type.

vercel Bot temporarily deployed to Preview October 27, 2026 21:32 Inactive

sentry-warden Bot reviewed Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/commands/cli/upgrade.ts

Comment thread packages/cli/src/commands/cli/upgrade.ts

BYK requested changes Oct 27, 2026

View reviewed changes

Comment thread packages/cli/src/lib/db/backup.ts

Comment thread packages/cli/src/lib/db/backup.ts Outdated

vercel Bot temporarily deployed to Preview October 27, 2026 21:59 Inactive

ref(cli): Remove the database's write-ahead log files in parallel

e4586e5

vercel Bot temporarily deployed to Preview October 27, 2026 22:02 Inactive

BYK approved these changes Oct 27, 2026

View reviewed changes

BYK enabled auto-merge (squash) October 27, 2026 22:03

BYK merged commit 0315e47 into main Oct 27, 2026
22 checks passed

BYK deleted the feat/cli-upgrade-undo branch October 27, 2026 22:14

Conversation

sentry-junior Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BYK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sentry-junior Bot commented Oct 27, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This branch was previously deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

sentry-junior Bot commented Oct 23, 2026 •

edited

Loading

vercel Bot commented Oct 23, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading

cursor Bot left a comment •

edited

Loading