Download the PHP package byte8/module-migration-forecast without Composer

Migration Forecast for Magento 2 and Mage-OS

Know what setup:upgrade will do to your database before you run it.

The module adds two commands:

Example output (illustrative figures):

setup:db:forecast is read-only: it never alters the database, never writes a file, and never fails a build unless you give it a limit. Neither command replaces, wraps or alters setup:upgrade itself.

Why

setup:db:status tells you that an upgrade is needed. --dry-run tells you which SQL will run. Neither tells you whether that SQL finishes in a blink or holds a lock on sales_order_item for four minutes — which is the only thing you need to know to decide if a release can go out at 2 PM.

Install

The only dependency is the framework itself. There is nothing to configure, no licence key, no telemetry and no network call of any kind.

Compatibility

On Mage-OS the requirement on magento/framework is satisfied by mage-os/framework, so composer require works unchanged — no patches, no alternative package.

Commands

setup:db:forecast

Run it on the new code, before setup:upgrade:

Gate a deploy with it:

setup:guarded-upgrade

Forecast and upgrade in one step. It prints the forecast and then runs the real setup:upgrade, in a separate process, exactly as if you had typed it.

At a terminal it asks Run setup:upgrade now? [y/N] before proceeding. It does not ask when nothing is pending.

Unattended (CI, deploy scripts, anything without a terminal) it never prompts. The limits you pass decide:

Without any limit, an unattended run always proceeds — set at least one for it to guard anything. Of setup:upgrade's own options only --keep-generated is passed through; for the others, run the two commands separately.

GitHub Actions

Run it where setup:upgrade would run — on the server, or over SSH from the workflow — because the forecast needs the live database.

JSON output

bin/magento setup:db:forecast --format=json prints one object:

kind is one of new_table, drop_table, modify_table, recreate_table, add_column, drop_column, modify_column, add_index, drop_index, add_constraint, drop_constraint.

How it works

1. The diff is Magento's own. Both commands ask the declarative-schema engine for the difference between the merged db_schema.xml files and the live database — the exact operation list setup:upgrade executes, db_schema_whitelist.json rules included.

2. Each operation is classified against MySQL 8 / InnoDB's online-DDL matrix:

   Change	Algorithm	Rebuilds table	Writes during it
   New / drop table	metadata	no	allowed
   Add column	INSTANT	no	allowed
   Add auto-increment column	INPLACE	yes	blocked
   Drop column	INPLACE	yes	allowed
   Modify column: comment or default	metadata	no	allowed
   Modify column: extend VARCHAR within the same length-byte class	INPLACE	no	allowed
   Modify column: nullability	INPLACE	yes	allowed
   Modify column: anything else (type, shrink, unsigned…)	COPY	yes	blocked
   Add index / unique / foreign key	INPLACE	no	allowed
   Add FULLTEXT index	INPLACE	no	blocked
   Add primary key	INPLACE	yes	allowed
   Drop index / unique / foreign key	metadata	no	allowed
   Drop primary key	COPY	yes	blocked
   Table engine / charset / resource	COPY	yes	blocked
   Any rebuild of a table that has a FULLTEXT index	—	yes	blocked

3. Row-scaled operations are costed from information_schema row counts and a throughput per class. Magento folds all changes to one table into a single ALTER, so a table is rebuilt once however many changes force it.
4. What cannot be costed is listed, not guessed. Pending data patches, schema patches and legacy Install/Upgrade scripts are arbitrary PHP. They are named beside the DDL forecast and never folded into it: the seconds you see are DDL plus bootstrap, nothing else.

Confidence

Confidence describes the DDL figure only. A pending patch does not lower it — a release with a trivial data patch still gets a trustworthy DDL forecast, and the patch is reported on its own line for you to judge.

Use --fail-on-uncosted if you would rather stop a pipeline whenever a patch is pending than review it by eye.

Limits

• It is an estimate. Row counts for InnoDB are approximate and the default throughputs are conservative guesses for mid-range hosting. Time one real ALTER on your host and pass --inplace-rate / --copy-rate.
• When in doubt it assumes the slower class. A dropped column is costed as a rebuild although MySQL 8.0.29+ can often do it instantly; a foreign key is costed as an index build although one may already exist.
• Metadata-lock waits are not modelled. Even an instant ALTER queues behind a long-running transaction on the same table.
• Modules missing from app/etc/config.php are enabled by setup:upgrade but are invisible to the diff until then. The command warns about each one.
• MariaDB follows the same matrix closely enough for the classification to hold, but it was written against MySQL 8's documentation.
• Split databases: tables on a non-default connection are sized through their own connection, but this path is not covered by CI.

Open source and Mage-OS

This module is open source under the MIT licence and works on Mage-OS. It is developed in the open at github.com/byte8io/magento-migration-forecast and distributed through Packagist, which also lists it in the Mage-OS Extension Directory.

Its maintainer is a member of the Mage-OS Association. The module is an independent Byte8 project; it is not an official Mage-OS package.

Contributing

Issues and pull requests are welcome — above all, real measurements. If the forecast was wrong on your store, that is the most useful thing you can tell us.

• CONTRIBUTING.md — setup, checks, how to change the matrix
• SECURITY.md — reporting a vulnerability
• CODE_OF_CONDUCT.md
• CHANGELOG.md

The unit tests are framework-free and run from a plain clone with phpunit.

Credits

Built and maintained by Byte8. Extracted from the migration-intelligence engine in Orbit, Byte8's zero-downtime deployment service for Magento, where the same forecast sizes the traffic-hold window for each deploy.

Licence

MIT — see LICENSE.txt.