Skip to content

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:

Terminal window
backup="loomarr-$(date +%F).db"
umask 077
curl -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.

Terminal window
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

Terminal window
NEXT_VERSION=0.2.0-beta.8 # replace with the exact release you intend to run
LOOMARR_VERSION="$NEXT_VERSION" docker compose -f docker/compose.yaml --profile sqlite pull
LOOMARR_VERSION="$NEXT_VERSION" docker compose -f docker/compose.yaml --profile sqlite up -d

Use the Postgres override files from the install guide for a Postgres deployment.

Migrations run at boot. Watch the first start:

Terminal window
docker logs -f loomarr
curl -fsS http://localhost:8080/v1/readyz && echo ready

The 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.db aside, along with any loomarr.db-wal and loomarr.db-shm beside it. Copy the newest /data/backups/pre-migration/loomarr-pre-*.db to /data/loomarr.db and give it uid/gid 65532. Set LOOMARR_VERSION to 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, set LOOMARR_VERSION to 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_VERSION to 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 traefik

    Confirm 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.