Skip to main content

​
Upgrading & Downgrading

Crewship is a single binary plus a crewship-sidecar runtime that ships alongside it. Upgrading swaps the binary; the database migrates itself on the next start, behind an automatic snapshot. Rolling back a binary is one step (self-update keeps a .bak), but once migrations have run, recovery also requires restoring that pre-migration snapshot — see Rollback / downgrade below.

​
Upgrade: crewship self-update

One command, whatever platform you’re on: 
crewship self-update            # upgrade to the latest release
crewship self-update --check    # report whether a newer release exists, change nothing
self-update picks the right mechanism from how crewship was installed:
Install methodWhat self-update does
Homebrew (brew install crewship-ai/tap/crewship)Runs brew upgrade <formula> for you (crewship or crewship-cli, whichever you have).
Installer / tarball (install.sh, or a downloaded archive)Downloads the release asset for your OS/arch and build variant (full crewship vs crewship-cli), verifies its SHA-256 against checksums.txt, backs up the current binary to <binary>.bak, then atomically swaps the running binary in place — plus the bundled crewship-sidecar and entrypoint.sh when they sit alongside it. It re-runs the new binary’s version as a sanity check and rolls back from the backup if that fails.
System package / read-only path (apt, rpm, a container image)Refuses to overwrite a file it doesn’t own, and prints the exact command to use instead (apt-get install --only-upgrade crewship, dnf upgrade crewship, docker pull …, or a reinstall via install.sh).
The download is checksum-verified before anything is swapped, and the swap is atomic (write-temp-then-rename), so an interrupted update never leaves a half-written binary. The previous binary is kept at <binary>.bak for a manual rollback. self-update only acts when a newer release actually exists — otherwise it reports you’re already current and exits.
The SHA-256 check confirms the download matches the published checksums.txt; it does not verify the file’s cosign signature. To verify provenance end-to-end (Sigstore keyless signature), use install.sh with cosign installed, or verify manually per the release notes.
self-update needs a released binary. A development build (version = dev, e.g. go run ./cmd/crewship) refuses — there’s nothing to compare against.

​
Migrations run on the next start

self-update swaps the binary only. Schema migrations apply on the next crewship start, and Crewship takes a pre-migration snapshot first (<database>.pre-migrate-v<from>-to-v<to>-<timestamp>.bak, next to your DB). So the upgrade flow is: 
crewship self-update
crewship start          # migrations apply here, after an automatic snapshot

​
Rollback / downgrade

Migrations are forward-only. An older binary will refuse to start against a database a newer binary already migrated — with an error naming both versions — rather than silently corrupt data it doesn’t understand: 
database schema is at v134 but this Crewship binary only understands up to v130:
the database was migrated by a NEWER Crewship. … either upgrade this binary … or
restore the pre-migration snapshot taken before the upgrade.
So downgrading is two steps, not one:
  1. Reinstall the older binary. Homebrew: brew install crewship-ai/tap/crewship@<version> (or brew uninstall + install the pinned tag). Installer: CREWSHIP_VERSION=vX.Y.Z curl -fsSL …/install.sh | bash.
  2. Restore the matching pre-migration snapshot — the *.pre-migrate-*.bak file taken just before the upgrade you’re undoing. Stop crewship, replace the live database file with the snapshot, and start the older binary.
Skipping step 2 leaves the newer schema in place, which the older binary rejects on start (by design). See Migrations for the version-skew guard and snapshot naming.
  • Migrations — the forward-only guard + pre-migration snapshots.
  • Backup & restore — full backup bundles vs. the automatic migration snapshots.
  • crewship doctor — reports when a newer release is available.