Magento describes the database you want. Laravel records how you got there. A column rename shows the difference: in Magento it can drop the column with its data, and the dry run that would warn you has a side effect of its own.
Magento: the file is the state
db_schema.xml describes each table as it should be. You change the file, you run bin/magento setup:upgrade, and Magento compares the XML with the live MySQL schema and writes the ALTERs itself. You don't get a history of steps. You get a diff.
One more file takes part. db_schema_whitelist.json lists the columns, indexes and constraints Magento is allowed to drop.
Laravel: the history is the state
Migrations are steps. Each file runs once, and a row in the migrations table remembers it: the file name and the batch number. The schema you have is what those steps added up to.
The rename is Magento's trap
Take a 2-column table with 3 SKUs, MB01, MB02 and WJ03, and rename sku to product_sku.
In Magento, a renamed column in the XML looks like one column gone and a new one added. With the old column in the whitelist, setup:upgrade runs 1 ALTER with 2 parts: ADD COLUMN product_sku and DROP COLUMN sku. All 3 rows end up with an empty product_sku.
The fix is one attribute on the new column: onCreate="migrateDataFrom(sku)". With it, the same upgrade copies all 3 values across before it drops the old column.
<table name="acme_export_log" resource="default" engine="innodb"> <column xsi:type="int" name="entity_id" identity="true" unsigned="true"/> <!-- was "sku": without onCreate, a whitelisted sku is dropped with its data --> <column xsi:type="varchar" name="product_sku" length="64" nullable="false" onCreate="migrateDataFrom(sku)"/> <constraint xsi:type="primary" referenceId="PRIMARY"> <column name="entity_id"/> </constraint> </table> Without sku in the whitelist, Magento keeps the old column and its data and adds an empty product_sku next to it. Nothing is lost, but now you have both.
Magento also has a net for the drop itself. setup:upgrade --safe-mode=1 dumps a column to a CSV in var/declarative_dumps_csv before dropping it. In the test the 3 SKUs were in that file, and --data-restore=1 put them back once the column was in the XML again.
Read the SQL first, on a copy
setup:upgrade --dry-run=1 writes the planned SQL to var/log/dry-run-installation.log and doesn't touch the tables. The drop is right there in the log. With migrateDataFrom the log shows the same ADD and DROP, and no copy, so read the XML too.
Write the =1. With a bare --dry-run, the same command ran the real upgrade: the log stayed empty and a pending column was added to the table.
The dry run isn't free, though. It still flushes the cache, and without --keep-generated it empties generated/code, generated/metadata, pub/static and var/view_preprocessed: the compiled code and the deployed static files. Don't point it at a production site. Run it on a staging copy, with the flag.
# planned SQL goes to var/log/dry-run-installation.log # =1 is required: a bare --dry-run runs the real upgrade # --keep-generated: without it generated/ and pub/static are emptied bin/magento setup:upgrade --dry-run=1 --keep-generated Laravel's trap is a different one
Laravel's rename itself is safe: a new migration with renameColumn() on the Blueprint, and a down() that renames it back. php artisan migrate --pretend prints the SQL without running it. On SQLite that's alter table "export_logs" rename column "sku" to "product_sku". After the real run all 3 SKUs are still there, and a rollback brings sku back.
// new file: the create migration already ran and won't run again return new class extends Migration { public function up(): void { Schema::table('export_logs', function (Blueprint $table) { $table->renameColumn('sku', 'product_sku'); }); } public function down(): void { Schema::table('export_logs', function (Blueprint $table) { $table->renameColumn('product_sku', 'sku'); }); } }; The tempting mistake is to edit the old create migration instead. On a fresh database, like the one your tests build, the edited file runs and everything passes. Where the migration already ran, migrate answers "Nothing to migrate" and the table keeps sku. That includes production.
One exception on the Magento side
Data patches are steps too. Each one runs once, and Magento logs it in patch_list. A fresh Magento 2.4.9 install from the GitHub repository had 171 rows there: 166 data patches and 5 schema patches. So Magento doesn't pick one model. It's state for most of the structure and steps for the data.
The rule
Review the two differently. In Magento, read the schema diff and the dry-run SQL on a staging copy, and check that every renamed column has migrateDataFrom. In Laravel, never edit a migration that already ran, and read --pretend before you deploy.
Next: why product attributes live in 6 tables, EAV next to a JSON column.
How does your team catch a destructive schema change before it ships?
Part 7 of 15 of the Magento 2 vs Laravel series. Originally published on LinkedIn.
