Percona 8 upgrade readiness — codebasecheck

A BOA host runs one shared Percona server for every Octopus instance, the Ægir Hostmaster front end, and every hosted site. Because the whole box shares that one server, a box-wide upgrade from Percona 5.7 to 8.0/8.4 — required to host Drupal 11 — is gated by the box's oldest, least-compatible codebase: a single account that cannot run on MySQL 8 blocks the upgrade for every other account on the host.

codebasecheck answers, before you start the upgrade, which accounts (if any) block it — so you can move just those to a legacy Percona 5.7 host and let the rest upgrade, rather than discovering the problem mid-upgrade.

This is not a hard break for legacy Drupal in general: BOA already serves Drupal 6, 7, and Backdrop on a single Percona 8.4 instance (relaxed sql_mode plus mysql_native_password), and its own managed cores are new enough to qualify. The check exists for the tail — a customer's frozen custom platform on an old core, or a site whose contrib code trips over MySQL 8.

What counts as compatible

Core version is the primary gate. The thresholds match the releases where each Drupal line gained MySQL-8 support, so in practice they only flag a codebase pinned to an old core:

A flagged codebase means that account must move to a legacy Percona 5.7 host before this box can upgrade — see Cross-host migration.

Running the check

codebasecheck <platform-path>    # check one codebase
codebasecheck --box              # box-wide readiness report (all accounts)
codebasecheck --box --deep       # box report + deep contrib/schema analysis

Single-codebase mode is also what the nightly maintenance runs per platform when /etc/boa/.allow-codebasecheck.cnf exists, recording per-platform findings under each account's log/ctrl/.

--box walks every /data/disk/<user> Octopus account, resolves each account's platforms from its Drush aliases, classifies them, and rolls the result up per account — the unit you actually migrate:

Account o3: READY (22 codebase(s))
Account o7: BLOCKED
    BLOCK   /data/disk/o7/static/legacy/oldsite  [7.44]  Drupal 7 (7.44) predates 7.76 MySQL-8 support
...
RESULT: BLOCKED — these account(s) must move to a legacy Percona 5.7 VM before this box upgrades:
  - o7

Each run also writes a full report to /var/log/boa/core/box-readiness-<timestamp>.log.

Verdicts and exit codes

Deep contrib/schema analysis

A codebase can pass the core-version check yet still break on 8.x through contrib or custom code and schema. --deep adds the REVIEW tier, driven by a small set of high-precision, low-noise signals (deliberately narrow — a check that flags every host is useless). It uses the local MySQL root access (/root/.my.cnf) and skips cleanly if that is unavailable.

• utf8mb3 tables — reported as INFO only; it does not change the verdict. utf8mb3 runs fine on Percona 8.4, so this is a heads-up that a utf8mb4 conversion is pending if you need 4-byte or emoji data, not a blocker.
• Reserved-word contrib table names — a table named with a MySQL-8 reserved word (for example groups or rank), excluding the core system table, which the database layer always quotes. Flagged REVIEW. Reserved-word columns are intentionally not scanned: they are pervasive (key, order, group, …) and always quoted by the schema layer, so flagging them would be pure noise.
• Static code red-flags in contrib/custom modules — NO_AUTO_CREATE_USER (a removed sql_mode that raises an error on 8.x and cannot be restored) and the removed TYPE=<engine> CREATE TABLE syntax.

A REVIEW result means look before you trust the upgrade, not broken. The reserved-word failure only fires when a module runs raw, unquoted SQL against the identifier — which cannot be proven from the schema alone — so --deep surfaces the risk for a human to verify on a test clone; it is not a guarantee of safety.

Plain --box needs no database access and is fast. --deep scans every platform's module tree and every database, so it takes noticeably longer on a busy host.

Before a Percona 8 upgrade

1. Run codebasecheck --box --deep.
2. If BLOCKED, move the named account(s) to a legacy Percona 5.7 host (Cross-host migration), then re-run.
3. If REVIEW, check each finding on a test clone (raw SQL against a reserved-word table, a flagged module).
4. When READY, run the staged upgrade — barracuda up-lts system percona-8.0 then barracuda up-lts system percona-8.4 — as covered in Percona install + tuning and the major OS upgrade (Percona 8.4 is a precondition for the Devuan Excalibur upgrade).