db:compatibility

Assesses whether the installed (or a proposed target) application/database combination is officially supported.

info

Read-only command. Evaluates the detected Magento/Adobe Commerce/Mage-OS version, edition and deployment context against a versioned compatibility dataset shipped at ./res/db-compatibility.json, and optionally against a proposed target version/database. Mage-OS is detected as its own product (it has its own version numbering, e.g. 3.0.0, distinct from Magento's 2.4.x) rather than being evaluated as plain Magento. A "supported" result confirms dataset-based version compatibility only - it does not certify schema, data, extension, or migration compatibility.

n98-magerun2.phar db:compatibility [options]

Examples:

n98-magerun2.phar db:compatibility
n98-magerun2.phar db:compatibility --target-version=2.4.9
n98-magerun2.phar db:compatibility --target-version=2.4.9 --target-db=mariadb --target-db-version=11.8
n98-magerun2.phar db:compatibility --online
n98-magerun2.phar db:compatibility --format=json

Options:

Option	Description
--target-version=TARGET-VERSION	Application version to evaluate instead of the detected one, e.g. 2.4.9
--target-db=TARGET-DB	Database family to evaluate instead of the detected one: mysql or mariadb
--target-db-version=TARGET-DB-VERSION	Database version to evaluate instead of the detected one, e.g. 10.11 or 11.4
--format=FORMAT	Output format: text (default) or json
--online	Additionally check the current/target application version live at magento.watch, and prefer that over the bundled dataset when it succeeds
--timeout=TIMEOUT	Bounded timeout in seconds for the optional --online check and MariaDB lifecycle lookup (default: 5)
-v, --verbose	Show the full evaluated-configuration table, dataset metadata, finding IDs, source citations, and the database lifecycle table (see below)

Output:

Standard output keeps to the essentials: a one-line summary of what was evaluated, and the support status with the reason. Pass -v for the full picture:

• The fully evaluated configuration (product, edition, deployment context, application version, database family/version) as a table - both current and target columns when --target-* is used, current only otherwise.
• Dataset metadata (revision, publication date).
• A stable finding ID and full source citation(s) (title, URL, verification date) per result.
• Database lifecycle information (status, support type, EOL date) for MariaDB versions as a table, fetched live from the MariaDB Foundation downloads REST API on a bounded timeout - this is purely informational and never affects the support verdict.

Always shown, regardless of -v:

• Support status (supported, unsupported, or unknown) with the requirement text, kept separate from recommendations.
• Recommended database versions, with rationale and the recommending organization, where the dataset provides one.
• Migration guidance when the target database family differs from the current one (e.g. MySQL to MariaDB).
• With --online: whether each result came from a live magento.watch check or fell back to the bundled dataset.

--format=json always includes everything above regardless of -v - it's a stable machine-readable contract, not a terminal UX concern.

Exit code: non-zero when the current (detected) installation is assessed as unsupported. An unknown result, or an unsupported result for a target configuration only, does not fail the command - this is intended for upgrade planning, not a strict gate. sys:check integration with a strict mode is tracked separately.

The dataset:

./res/db-compatibility.json is a versioned, schema-validated dataset (see ./res/db-compatibility.schema.json) describing which Magento/Adobe Commerce/Mage-OS versions officially support which MySQL/MariaDB versions, with source references and verification dates. Most of it is generated by scripts/import-db-compatibility-dataset.php from magento.watch, an independent, open, no-auth community API that tracks exact per-release requirements for magento-community, magento-commerce, and mage-os; a small hand-authored remainder covers explicit "known unsupported" versions and MySQL→MariaDB migration guidance, which magento.watch doesn't provide. Re-run the importer to refresh it (.agents/skills/db-compatibility-refresh/SKILL.md documents the full maintainer workflow). ./build.sh re-validates the bundled file before a release build (see --skip-dataset-fetch). db:compatibility itself always evaluates against the bundled snapshot; pass --online for a live per-version check against magento.watch instead.