CouchDB B-tree Format Recovery After Interrupted Major Version Upgrade

Goal

Determine whether CouchDB can safely recover from an interrupted major version upgrade when the on-disk B-tree format has been partially migrated by the upgrade script.

Constraints

During a major version upgrade (e.g., 3.x to 4.x), CouchDB executes an Erlang-based upgrade script that transforms system databases and may rewrite user database headers. This process modifies data in place without transactional guarantees.

Uncertainty

If the upgrade script fails mid-execution, the B-tree format may exist in a hybrid state that is unreadable by both the old and new CouchDB binaries. The official documentation states that rollback requires restoring from a pre-upgrade backup, but does not specify recovery procedures for scenarios where system databases are partially migrated.

Questions

• Can CouchDB detect and automatically repair a partially migrated B-tree after an interrupted upgrade, or is manual intervention always required?
• What specific data structures or metadata flags indicate whether a database header has been fully migrated to the new format?
• Is there a documented procedure to verify B-tree integrity across system databases before and after an upgrade?