Upgrade Path
此内容尚不支持你的语言。
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.
The standard upgrade
Section titled “The standard upgrade”# 1. Read the release notes# https://github.com/engram-app/engram/releases
# 2. Pull the new imagedocker 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 imagedocker compose up -d engram
# 5. Watch the logs for migration completiondocker compose logs -f engramEngram runs database migrations on startup. The first boot of a new version may take a few seconds longer while migrations apply.
Reading release notes
Section titled “Reading release notes”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.
Qdrant version steps
Section titled “Qdrant version steps”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 releases | Qdrant pin |
|---|---|
| 0.57.0 and earlier | 1.17.1 |
| 0.58.0 and later | 1.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.
# Stop Qdrant so the copy is consistentdocker 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 qdrantIf 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:
docker compose stop qdrant
# Empty the volume, then unpack the tarball into itdocker 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 qdrantWithout 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.
What changes with each Qdrant version
Section titled “What changes with each Qdrant version”- 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=falseturns 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=trueto keep a disk guard.
Rollback
Section titled “Rollback”If the new version doesn’t behave:
- Stop the app:
docker compose stop engram - Pin the old image tag in your compose file
- If migrations are reversible:
bin/engram eval 'Engram.Release.rollback(Engram.Repo, <VERSION>)'(the release wraps Ecto’s migrator) - If migrations are one-way: restore from your most recent pre-upgrade backup
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.
Major version bumps
Section titled “Major version bumps”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.