Upgrade and roll back Barry

Use this when you move a Barry installation onto a newer release, or return it to the one it ran before. barry upgrade snapshots the stores, migrates a copy of them when their schemas change, switches to the new release, restarts the services, and verifies them. barry upgrade --rollback undoes the last upgrade.

Before you begin

The installation runs from a release. barry upgrade installs the release it runs from, so it refuses to run from a linked checkout. If you installed Barry by following Build a Barry, you run a linked checkout; see Update a linked checkout instead.
You have the new release extracted on disk: a verified release artifact supplied to you. The upgrade never fetches a release on its own, and Homebrew releases remain experimental.
You run as the installation’s own user, not as root.
You have a fresh backup, as in Back up and restore Barry’s stores. The upgrade takes its own snapshot, but a backup you made yourself is the one you can restore anywhere.

Update a linked checkout

A linked checkout updates through setup, not barry upgrade. From your Barry checkout, pull the new code, rebuild the packages, and reconcile the installation:

git pull
pnpm install --frozen-lockfile
pnpm build:packages
barry setup --link .

Changed checkout code takes effect only after you rebuild the packages. The rest of this page covers release installations.

Upgrade

Run the upgrade with the new release’s own entry point, from the directory you extracted it into:

./bin/barry upgrade

Before it changes anything, the command prints the plan: the current and target installation, any store schema that changes, the user services it restarts, and any session still running. System services keep their code; the plan says so. Confirm to go ahead. To run it from a script, add --yes, which an upgrade with no terminal attached requires.

The upgrade then prints the path of the snapshot it took, stops the user services, prepares and checks a migrated copy of the stores when a schema changes, switches to the new release, runs setup and a bag build from it, and restarts the services. When it finishes, it lists any system service that needs the privileged pass, which you run next:

sudo barry setup --system

Running the same release a second time reports that the installation already uses it and changes nothing.

Roll back

To return to the release, or linked checkout, that the last upgrade replaced:

barry upgrade --rollback

When the upgrade migrated the stores, the rollback also brings back the store generation from before the upgrade, so the older release reads stores it understands. Writes made since the upgrade stay in the newer generation and in a snapshot, and the rollback says so before you confirm. The rollback refuses when it cannot run safely: when the stores changed since the upgrade, when the last change was already a rollback, or when the earlier installation is missing from disk. When it refuses because the stores changed, it names the snapshot taken before the upgrade, so you can inspect it before you decide what to restore.

Rolling back the code is not permission to restore an older database over a live installation. To restore stores, use barry db restore.

Verify

Check the version, then the installation’s health:

barry --version
barry doctor --strict
barry service status
barry store verify

The version matches the release you upgraded to. doctor --strict exits non-zero when any installation check fails, service status exits non-zero when a service needs attention, and store verify checks each store’s integrity.

If it fails

The upgrade reports an interrupted store switch. Run barry db recover to finish the switch, or undo it when it cannot finish, then run the upgrade again.
An earlier upgrade or rollback never finished. The error names the command that finishes it: the target release’s own bin/barry upgrade, or barry upgrade --rollback.
The upgrade switched, but setup or the bag build failed. Run the upgrade again to finish, or roll back.
The stores are newer than the release. The release refuses stores stamped by a newer schema. Upgrade to a release at least as new; see A store refuses to open after an update.
The stores are not in a store generation yet. An upgrade that changes a schema needs one. Run barry db backup, restore that backup with barry db restore, then upgrade again.