Upgrade Loomarr
For: household admins moving to a new release. You’ll get: a backup you can restore, the new version running, and a way back if it goes wrong.
Migrations only run forward. On SQLite, Loomarr keeps its own way back: when a new release finds migrations to run, it first copies the database, checks the copy, and only then migrates. So on SQLite an upgrade is pull, then restart, and Loomarr is down for the restart and migrations alone, a matter of seconds. On Postgres, back up, then pull.
The copy Loomarr keeps (SQLite)
Before migrating, Loomarr writes /data/backups/pre-migration/loomarr-pre-<from>-to-<to>-<time>.db,
where <from> and <to> are the schema versions. It runs SQLite’s quick_check on the copy and
keeps the newest three.
If the copy can’t be made or doesn’t check out (most often, too little free disk: it needs about the database’s size), Loomarr does not migrate. It exits, and the log says why. The database stays as the previous release left it, so the previous image still starts. Free some space and start again.
The copy holds encrypted credentials but not the key that opens them, so keep /data/encryption.key
(or your LOOMARR_ENCRYPTION_KEY secret) as you always have.
Back up
You can still take a backup of your own, and should keep one off the host. On Postgres, it is the only way back.
The simplest way is the admin UI: Settings → System → Backup, which downloads a snapshot with your signed-in session — no token needed. To script it instead, use the endpoint below.
/v1/backup is admin-only. The API_TOKEN it needs is not the internal one Loomarr
auto-generates; reveal a usable value under Settings → Secrets (eye toggle + copy), or set your
own API_TOKEN=<something-long> in .env and restart. Export it as $API_TOKEN before the curl —
without it the request is 401.
SQLite — this streams a consistent snapshot while the app runs:
backup="loomarr-$(date +%F).db"umask 077curl -fsS -H "Authorization: Bearer $API_TOKEN" \ http://localhost:8080/v1/backup > "$backup.partial" && chmod 600 "$backup.partial" && mv "$backup.partial" "$backup"Postgres — create the custom archive pg_restore expects. Loomarr’s image ships no Postgres client
and the supported Compose stack keeps the database off the host network, so run the client inside
the Postgres service and stream the archive to the trusted host; /v1/backup returns 501 there.
compose=(docker compose -f docker/compose.yaml -f docker/compose.postgres.yaml --profile postgres)archive="loomarr-$(date +%F).dump"umask 077"${compose[@]}" exec -T postgres sh -ceu \ 'pg_dump --format=custom --username="$POSTGRES_USER" --dbname="$POSTGRES_DB"' \ > "$archive.partial" && chmod 600 "$archive.partial" && mv "$archive.partial" "$archive"Database backups contain encrypted credentials and wrapped data keys, but not the external installation key needed to decrypt them.
The application backup is database-only. Copy /data separately if you need operator-uploaded
images or filler files; cached artwork can be regenerated. Keep at least one
backup off the Loomarr data volume and, ideally, off the host.
Preserve /data/encryption.key separately from the database backup, or preserve the external
LOOMARR_ENCRYPTION_KEY / _FILE secret used by every replica. A database restore cannot recover
stored credentials without that same installation key.
To replace the key deliberately, supply the new current key and the old key through
LOOMARR_ENCRYPTION_KEY_PREVIOUS (or _PREVIOUS_FILE) for one successful boot. Loomarr rewraps the
database data keys atomically. Remove the previous-key input afterward; it is maintenance material,
not a permanent fallback.
Pull
NEXT_VERSION=0.2.0-beta.8 # replace with the exact release you intend to runLOOMARR_VERSION="$NEXT_VERSION" docker compose -f docker/compose.yaml --profile sqlite pullLOOMARR_VERSION="$NEXT_VERSION" docker compose -f docker/compose.yaml --profile sqlite up -dUse the Postgres override files from the install guide for a Postgres deployment.
Migrations run at boot. Watch the first start:
docker logs -f loomarrcurl -fsS http://localhost:8080/v1/readyz && echo readyThe app does not listen until migrations finish. A failed migration appears in the container log;
once the listener is up, /v1/readyz reports runtime readiness.
Rolling back
Restore the backup, then run the older image.
-
SQLite, from the copy Loomarr kept — stop the container. Move
/data/loomarr.dbaside, along with anyloomarr.db-walandloomarr.db-shmbeside it. Copy the newest/data/backups/pre-migration/loomarr-pre-*.dbto/data/loomarr.dband give it uid/gid 65532. SetLOOMARR_VERSIONto the release you came from, and start it. Anything recorded after the upgrade began is lost; everything before it is there. -
SQLite, from your own backup — stop the container, replace
/data/loomarr.db, restore ownership to uid/gid 65532, setLOOMARR_VERSIONto the older version, and start it. Confirm/v1/readyz, then sign in and inspect a channel before discarding the newer backup. -
Postgres — use the same Compose files as the running stack, stop Loomarr, replace only the Loomarr database, set
LOOMARR_VERSIONto the older version, and start with the Postgres override. The replacement database is owned by the configured Postgres user:Terminal window compose=(docker compose -f docker/compose.yaml -f docker/compose.postgres.yaml --profile postgres)"${compose[@]}" stop loomarr"${compose[@]}" exec -T postgres sh -ceu 'dropdb --username="$POSTGRES_USER" --force "$POSTGRES_DB"createdb --username="$POSTGRES_USER" --owner="$POSTGRES_USER" "$POSTGRES_DB"pg_restore --username="$POSTGRES_USER" --dbname="$POSTGRES_DB" --exit-on-error' < loomarr-YYYY-MM-DD.dump"${compose[@]}" up -d loomarr traefikConfirm readiness, sign-in, and a channel before discarding the newer dump.
Running an older binary against a newer database isn’t supported. The new schema may contain changes the old code can’t read.
What survives
Everything on the /data volume: database, artwork cache, filler clips. Generated secrets live
in the database, so tokens don’t rotate on upgrade.
Check your compose file mounts /data — an upgrade is when you’d find out it doesn’t, because
pull recreates the container.