Forgejo restore across versions: pin the original release or upgrade during recovery?

Restore first, upgrade second

Restore onto the exact pinned release that produced the dump, verify the instance, then upgrade as a separate operation. Combining restore and upgrade merges two failure domains — backup fidelity and schema migration — into one irreversible step, and if anything goes wrong you cannot tell which half failed.

The reason this matters is the one-way property you already identified: on first startup, a newer Forgejo binary migrates the database schema to its own version, and downgrades are unsupported. If you point the latest binary at a freshly imported dump and the migration breaks, you have no intermediate known-good state. If you instead restore onto the original version, verify it, and take a fresh dump before upgrading, a failed migration costs you only a re-import, not a forensics session.

Confirmed vs. likely

Confirmed by the documented workflow: recovery is manual (import dump, unpack data, restore app.ini, fix ownership), and the guidance is to restore with the same version that produced the backup. Likely, based on Forgejo's Gitea lineage: schema migrations run automatically at first startup of a newer binary, are not wrapped in a single transaction, and are not guaranteed to be cleanly resumable after a mid-migration failure. Treat the lineage-derived details as needing confirmation against the release notes for your specific versions.

Answers to your three questions

• Restore-then-upgrade is the safer practice. Operators do sometimes combine the two for small instances, but the pinned-restore-then-upgrade sequence is what preserves a rollback point. There is no supported downgrade, so the upgrade moment should never also be the recovery moment.
• Forgejo keeps no pre-migration snapshot. If a migration fails partway, the database can be left partially migrated, and the only reliable recovery is re-importing the original dump. This is why the fresh pre-upgrade dump matters: it gives you a recovery point that already reflects the verified restore.
• forgejo doctor check is not a migration validator. It can surface orphaned data, repository/filesystem mismatches, and some database integrity issues, but a clean doctor run does not prove a migration completed correctly. Use it as one signal alongside functional tests, not as the verdict.

Recommended sequence

1. Restore the dump, repository root, app.ini (with original SECRET_KEY and INTERNAL_TOKEN), and APP_DATA_PATH onto the pinned binary. Fix ownership.
2. Start, run forgejo doctor check, then functional tests: clone, push, LFS fetch from S3, 2FA login. Do not skip the LFS fetch — LFS lives outside the dump, so a broken LFS config survives an otherwise clean-looking restore.
3. Take a fresh pg_dump of the verified instance. This is your pre-upgrade recovery point.
4. Swap to the newer binary, start, watch the migration log, then re-run doctor and the full functional suite. Compare counts of users, repositories, and issues against pre-upgrade values.

Two traps worth flagging

Mismatched SECRET_KEY or INTERNAL_TOKEN in app.ini silently invalidates sessions and tokens, which looks exactly like a corrupted restore — check this before suspecting the dump. And multi-version upgrades can include slow data migrations on large instances, so rehearse the upgrade in staging with a copy of the production dump to measure downtime before the real recovery.

One caveat: exact migration behavior and doctor subcommands vary by release, so confirm the specifics against the release notes for the versions spanning your dump and target. The one detail that would change this recommendation is how many schema versions separate the dump from the target — a same-major-version gap is low risk either way, while a multi-LTS jump makes the staged path close to mandatory.