Upgrades

meta.db holds Lumbung’s own records: databases, branches, tokens, the audit log. Each version embeds the migrations it needs and applies them when it starts. Migrations only go forward.

Upgrade

Back up meta.db:

docker compose exec -T engine lumbungd backup --to /data/backups --meta-only

Pull the new version and rebuild:
Terminal window
```
git pull
docker compose up -d --build
```
Check that it serves:
Terminal window
```
curl -s http://127.0.0.1:4870/health
```
/health reports the version and how many meta.db migrations are applied.

Branch files are plain SQLite and don’t change between versions.

Roll back

If a new version migrated meta.db, an older binary refuses to serve it: /health answers 503 with unavailable, and every request fails the same way, so a bad rollback is visible at once instead of quietly misreading newer records. To roll back:

Stop the engine:
Terminal window
```
docker compose stop engine
```
Check out the older version and build it:
Terminal window
```
git checkout v0.1.0
docker compose build engine
```
Put back meta.db from the backup you took before upgrading. restore --meta-only takes the newest meta-only backup in the folder, refuses to run while lumbungd is running, and keeps the current meta.db next to it as meta.db.before-restore-<time>:
Terminal window
```
docker compose run --rm engine restore --meta-only --from /data/backups
```
Start it:
Terminal window
```
docker compose up -d
```

Anything created between the upgrade and the rollback (databases, branches, tokens) isn’t in the old meta.db. Their files stay on disk, and the engine removes ones it doesn’t know at start. Records whose files were deleted since the backup are dropped by the restore.

Don’t copy meta.db over by hand: a leftover meta.db-wal from the newer version would be replayed onto the old file.