Aller au contenu

Upgrade Path

Ce contenu n’est pas encore disponible dans votre langue.

Engram upgrades are container-tag bumps + migration runs. Most are boring. A few have called out one-way migrations, so read release notes before bumping.

Terminal window
# 1. Read the release notes
# https://github.com/engram-app/engram/releases
# 2. Pull the new image
docker compose pull engram
# 3. Back up first if you haven't recently — pg_dump + mc mirror
# See: /docs/self-host/backup-restore/
# 4. Restart with the new image
docker compose up -d engram
# 5. Watch the logs for migration completion
docker compose logs -f engram

Engram runs database migrations on startup. The first boot of a new version may take a few seconds longer while migrations apply.

Look for:

  • BREAKING CHANGES: env var renames, dropped features, required manual steps
  • One-way migrations: irreversible schema changes; the previous version cannot boot against the new DB
  • Required min/max version steps: occasionally you must upgrade via an intermediate version (e.g. 0.5 → 0.6 → 0.7, not 0.5 → 0.7 directly)

When in doubt, restore your backup to a staging environment first and run the upgrade there before touching production.

The compose file pins the Qdrant image (qdrant/qdrant:vX.Y.Z). Qdrant only guarantees that it can open storage written by the previous minor version, so it must be upgraded one minor at a time, landing on the latest patch of each. Qdrant has no live downgrade: the only way back is to restore a copy of the storage taken before the upgrade.

Today’s state:

Engram releasesQdrant pin
0.57.0 and earlier1.17.1
0.58.0 and later1.18.3

If you pull each Engram release, Qdrant moves from 1.17.1 to 1.18.3 on its own, one minor step, and you do nothing extra. No Engram release pins 1.19 yet. Engram’s CI already tests against 1.19.2, and the release notes of the release that moves the pin will say how that step happens (tracked in engram-app/Engram#2227).

Copy the Qdrant volume before a Qdrant step

Section titled “Copy the Qdrant volume before a Qdrant step”

The backup guide does not back up Qdrant, because it can be rebuilt. A copy is still worth making before a release that changes the Qdrant pin: a failed step otherwise means a full re-embed of every note, which can take hours on a large vault.

Terminal window
# Stop Qdrant so the copy is consistent
docker compose stop qdrant
# Copy the volume to a tarball in the current directory
# (the volume is named <compose project>_qdrant_data; check with `docker volume ls`)
docker run --rm -v engram_qdrant_data:/from -v "$PWD":/to alpine \
tar czf /to/qdrant-backup.tgz -C /from .
docker compose start qdrant

If a step fails, go back to the previous Engram release first, so Qdrant runs the old pin again: the new image has already refused or migrated the storage. Then restore the copy into the volume:

Terminal window
docker compose stop qdrant
# Empty the volume, then unpack the tarball into it
docker run --rm -v engram_qdrant_data:/to -v "$PWD":/from alpine \
sh -c 'rm -rf /to/* && tar xzf /from/qdrant-backup.tgz -C /to'
docker compose start qdrant

Without a copy, rebuild the index from Postgres instead. That is manual today: see step 5 of the restore guide. Your notes are safe either way: Postgres is the source of truth, and Qdrant only holds the search index.

  • 1.18: Engram turns on Qdrant strict mode with disk and memory write guards (a refusal pauses indexing instead of failing it). QDRANT_STRICT_MODE=false turns the guards off.
  • 1.19: the disk guard moves to Qdrant’s node-wide quotas. Engram does not manage them by default, because quotas apply to every collection on the Qdrant server. If this Qdrant serves Engram alone, set QDRANT_MANAGE_QUOTAS=true to keep a disk guard.

If the new version doesn’t behave:

  1. Stop the app: docker compose stop engram
  2. Pin the old image tag in your compose file
  3. If migrations are reversible: bin/engram eval 'Engram.Release.rollback(Engram.Repo, <VERSION>)' (the release wraps Ecto’s migrator)
  4. If migrations are one-way: restore from your most recent pre-upgrade backup
  5. docker compose up -d engram

The “if migrations are one-way” branch is why always back up before upgrading isn’t paranoia. It’s the only escape hatch.

For major version transitions, the release notes typically include a section explicitly titled “Upgrade from X.Y to X.Y+1” with the exact steps. Follow it line by line. If anything is unclear, file an issue before running anything in production.