Forgejo 1.20 schema migration rollback safety after database upgrade

The direct answer

Forgejo 1.20 migrations are forward-only: each schema change is applied at startup with no paired down-migration in the binary, and an older binary will refuse to start against a database that has already been migrated to a newer schema version. As a result, the only safe, supported rollback today is restoring the pre-upgrade database backup and running the previous binary against it. There is no rollback command to invoke, and attempting to hand-write reverse SQL against a live database is the scenario most likely to cause silent corruption.

Why a binary downgrade alone fails

Forgejo tracks the applied schema version in the database. When an older binary starts, it compares its expected version against the stored one and stops rather than risk operating on a schema it does not understand. This is a deliberate guard, not a bug — it prevents the older code from misinterpreting new columns, renamed tables, or changed constraints. So the failure mode administrators hit ("I downgraded the package and now it won't start") is the system working as designed.

Should Forgejo add reversible migrations?

The likely explanation for the current design is that reversible migrations are expensive to maintain and still cannot cover every case. A down-migration for a dropped column cannot restore the data that column held; a split table cannot be un-split without ambiguity. Any rollback feature would therefore need, at minimum:

• Paired up/down scripts reviewed and tested for every migration, including data-preservation guarantees or explicit loss warnings.
• Transactional execution where the database engine supports DDL transactions, so a failed rollback cannot leave a half-applied state.
• A pre-rollback consistency check that refuses to proceed if post-upgrade writes have populated structures the down-migration would destroy.
• A recorded migration ledger so the tool knows exactly which steps to reverse and in what order.

Even with all of that, a rollback command would still be unsafe once new data has been written after the upgrade. That is a fundamental limitation, not an implementation detail — which is why backup restoration remains the honest recommendation regardless of what tooling is added.

The safe procedure today

1. Before upgrading, stop Forgejo and take a full database dump (for example pg_dump for PostgreSQL or mysqldump for MySQL/MariaDB), plus a copy of the data directory.
2. Record the exact previous binary version so you can restore the matching pair.
3. Upgrade and let migrations run. Verify the instance works before opening it to users.
4. If you must revert: stop the new binary, drop or move the migrated database, restore the dump, and start the old binary. Confirm the stored schema version matches what the old binary expects.

Test this path on a staging copy before you need it. A backup that has never been restored is an assumption, not a safeguard.

What the documentation should say

The upgrade docs should state plainly that migrations are one-way, that the backup is the rollback plan (not a precaution), and that restoring means restoring both the database and the matching binary version together. If a rollback feature is ever introduced, the docs should scope it explicitly to "no writes since upgrade" scenarios rather than presenting it as a general undo.

This reflects documented behavior up to Forgejo 1.20; migration internals can change between releases, so verify against the release notes and migration source for your exact version before planning around it.