Database migration lock contention in Forgejo startup

Operational boundaries of Forgejo startup migration

The internal database migrator is invoked during application start‑up and requires exclusive write access to the database. Until the migration completes, the HTTP server is not yet listening, so no request handling occurs; incoming requests are effectively blocked until the schema upgrade finishes.

Confirmed facts from the Forgejo startup sequence:

• The migrator executes as part of the initialization routine before the server binds to any port.
• Request handling begins only after the migration process returns successfully.

Potential failure conditions when multiple instances attempt to start against the same database during an upgrade:

• Database‑level lock contention can cause the migrator to fail with “database is locked” or similar errors.
• Duplicate schema‑change statements may lead to inconsistent or corrupted schema states.
• One instance may start serving traffic while another is still applying migrations, resulting in runtime errors such as missing columns.

Steps to define the operational boundaries for this case:

1. Inspect the Forgejo startup code (or consult the version‑specific release notes) to confirm that the HTTP server is started after the migration routine completes.
2. Verify that only a single instance is allowed to run the migration by stopping the existing service before replacing the binary and starting the new instance.
3. Perform a diagnostic test: launch a second Forgejo instance against a copy of the production database while the primary instance is migrating and record the startup logs and HTTP readiness.

Missing diagnostic detail that would change the recommendation:

• Whether the HTTP server binds to its listening port before the migration finishes (i.e., if the server is already accepting connections while the migrator is still running).