CouchDB Upgrade Utility: Recovering from Mixed-State Databases After an Interrupted 3.x to 4.x Transition

When moving a CouchDB cluster from 3.x to 4.x, the _upgrader REST endpoint rewrites database files in place while the node is offline. If the process is interrupted—by power loss, a kill signal, or manual termination—some .couch files may already be in the new format while others remain pre-upgrade. The result is a mixed-state data directory that can prevent startup or trigger view rebuild errors.

The documented recovery path is to restore the entire data directory from a pre-upgrade backup, because the upgrade utility does not provide an automatic rollback or checkpoint mechanism. Operators without a backup face a manual, error-prone cleanup: identifying partially migrated files, removing stray temporary artifacts, and deciding whether to re-run the upgrade from scratch or attempt a targeted repair. There is currently no built-in detection of a previous incomplete run, leaving the resume-or-restore decision entirely to the administrator.

Given that CouchDB 3.x to 4.x migrations rely on the _upgrader endpoint with exclusive data-directory access, what is the safest supported procedure when no pre-upgrade backup exists and the upgrade was interrupted mid-run? Should administrators assume the utility will never resume automatically and always plan for full restoration, or are there documented safeguards for detecting partial migrations before restarting the node? How do release notes for the 4.x line address configuration files that the endpoint does not migrate automatically after an interrupted run?