Skip to content

Upgrading and Versions

Tom Barber edited this page Nov 6, 2026 · 3 revisions

Upgrading and versions

This page is a short version of the repository's Versions, upgrades and uninstalling, which has the detail. Hairspring is experimental and changes quickly. The commands here were run on macOS with the v0.1-RC1 macOS binary and a build of main; anything needing Linux x86-64 is marked "not run here".

Which build do I have?

$ hairspring --version
hairspring 0.1.0 (0ba59f0 2026-11-05)

A current build prints the commit and its date after the version. The v0.1-RC1 pre-release prints only hairspring 0.1.0, so a bare hairspring 0.1.0 with no commit means the pre-release or another build older than that change. The release notes name the pre-release's commit: f819c1a, committed on 24 October 2026. A build from a source archive prints (unknown) in place of the commit. Quote the whole line when you report a problem.

Pre-release binary or a build of main?

The repository documentation describes main, which is ahead of the pre-release. Comparing each subcommand's --help, these exist only in builds newer than v0.1-RC1:

  • hairspring gc (the pre-release says error: unrecognized subcommand 'gc')
  • hairspring serve --trusted-proxy, --organisation, --max-connections and --max-replays (the pre-release says error: unexpected argument '--trusted-proxy' found, and so on)
  • hairspring test --confirm
  • the commit and date in hairspring --version

Only the command line was compared; server and web UI changes are not in that list. To use these, build from source (see Installation).

The schema-version error

A newer build migrates a results database in place and silently; an older build then refuses it:

$ hairspring results
error: storage error: database schema version 6 is not supported (expected 5)

(exit status 2). That text was printed by the v0.1-RC1 binary for a copy of a database made by main when main was at schema 6. main has since moved to schema 8, so the same binary on a database from a current main build gives database schema version 8 is not supported (expected 5) (derived from the code, not run). The numbers change as schemas are added; the meaning does not. The database is not damaged: your binary is older than the one that last opened it. Keep using the newer build everywhere that database is used, point the old binary at a different database with --db (which starts a new, empty set of results), or restore a backup taken beforehand. The CLI has no downgrade command.

Bundles from a newer build

A bundle written by a newer build can record environment fields an older build does not know. A build with this check says so when you replay it, and if the replay does not repeat the failure you get exit 3 instead of "not reproduced". Replay bundles from a newer build with a current build. Builds from before this check cannot warn.

Upgrade safely

  1. Back up: (umask 077; sqlite3 .hairspring/hairspring.db ".backup 'hairspring-backup.db'") (run, and read back with hairspring --db hairspring-backup.db results), or for PostgreSQL pg_dump -h db.internal -U hairspring hairspring > hairspring-backup.sql with the password in ~/.pgpass (mode 600), not on the command line (not run here).
  2. Stop every server and worker that uses the database. On PostgreSQL, the schema 8 upgrade also needs the first open to be the owner's and a grant for the other roles: see Installation.
  3. Upgrade the server and all workers together.
  4. Start the server, then the workers, and check hairspring --version on each.
  5. To go back, restore the backup. Anything stored after it is lost.

For running a server see Operate-a-Server.

Uninstall

What Default place Remove with
The hairspring command ~/.local/bin/hairspring rm ~/.local/bin/hairspring
Hermit, if installed ~/.local/share/hairspring/hermit rm -rf ~/.local/share/hairspring/hermit
Results and bundles .hairspring/ in each directory you ran hairspring in rm -rf .hairspring
Configuration hairspring.toml from hairspring init delete it if unwanted

The installers never use sudo. If you installed the Rust toolchain through Hermit's installer (--install-toolchain), rustup toolchain uninstall <toolchain> removes it, using the RUST_TOOLCHAIN named in scripts/hermit.pin (not run here). For the Python SDK, pip uninstall hairspring if you installed it with pip; for the other SDKs remove the dependency from your own project. For a server or worker set up as in the repository's deploy guide, also stop and remove the systemd units (hairspring and hairspring-worker; not run here). The hairspring system user, /etc/hairspring and /var/lib/hairspring (and /var/lib/hairspring-worker) are yours to keep or remove; nothing here deletes them for you, and the database is in /var/lib/hairspring, so back it up first if you may want the results. For Docker Compose, docker compose down stops the stack and docker compose down -v also deletes the PostgreSQL volume with all results (not run here).

Clone this wiki locally