Phoenix JDBC driver and SYSTEM.CATALOG compatibility after interrupted upgrade migration

When upgrading Apache Phoenix, the migration of the SYSTEM.CATALOG tables in HBase typically runs on the first connection from a newer JDBC client, modifying internal metadata structures. If that upgrade is interrupted or fails, the catalog may be left in an intermediate state that the previous version cannot interpret.

The core uncertainty sits at the integration boundary between the client-side JDBC driver and the HBase-stored metadata. Because Phoenix does not generally guarantee that upgraded catalog metadata remains readable by older clients, simply reverting the driver JAR may not restore service once the SYSTEM.* tables have been touched. Recovery planning therefore needs to account for catalog version, client driver, and region server coprocessor JARs as one aligned unit, with HBase snapshots of the SYSTEM.* tables taken beforehand as the likely rollback mechanism. Exact guarantees vary by version, and cross-major jumps such as 4.x to 5.x also change the required HBase version, so the specific release notes for the versions in use should be consulted.

• Can an older Phoenix JDBC client successfully query a system catalog that a newer version has partially migrated?
• Is there any documented way to detect and roll back a partially applied catalog migration without restoring HBase snapshots?
• What alignment is required between region server coprocessor JARs and the client driver when rolling back after a failed upgrade?