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

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

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.

Rollback

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.

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.