Changing migration logic

[chriscpty]

TL;DR: In my opinion, changes to migration logic should be considered breaking changes.

Background/Why this came up

For some background, we ran into a problem where on our intern's system, inserting a record into a table with a JSON column behaved differently than on everyone else's machines. The reason for this is that we created their system after updating to Yii2 2.0.50, which has this little line hiding in the changelog:

Enh #20171: Support JSON columns for MariaDB 10.4 or higher (terabytesoftw)

By adding this support, migrations that create a column as SchemaBuilderTrait::json() no longer just create a LONGTEXT column, but instead also add a json_valid constraint to it; In turn, when parsing the column schema, Yii2 starts treating the column as a JSON column, which changes how it (de-)serializes values (see yii\db\mysql\ColumnSchema::dbTypecast).

The problem/My suggestion

This means that any system created by running php yii migrate before the update to 2.0.50, which is most of our development and productive systems, behaves differently to systems created after the update. We now have to go back and change all our migrations where we used json to instead use text so that a newly created development system actually matches our productive one.

To avoid problems like this coming up again, future migration code changes should either be declared breaking changes or use some kind of versioning mechanism (e.g. via optional parameters that default to the old configuration).

[terabytesoftw]

https://github.com/yiisoft/yii2/blob/master/framework/UPGRADE.md#upgrade-from-yii-2050 What else needs to be added? Is it in Upgrade.md?

[chriscpty]

I'd say it should explicitly mention that this changes migration behaviour; Generally that text could do a better job of explaining what changed, rather than just that it changed, and (as an upgrade guide) focus on what I as a user need to do to adapt to this change. Something like:

The behaviour for the column type JSON in MariaDB databases changed. Columns that are created as JSON now automatically add a Check constraint for json_valid to the according column.
If Yii2 detects that a column has this json_valid constraint, data passed into or fetched from it is automatically serialized/deserialized.

While this does affect migrations created before the update when running them afterwards, it doesn't retroactively change tables created through migrations before the update! This means that running a migration script that invokes yii\db\Migration::json() for a MariaDB database will create a different database schema after the update than it did before.

To preserve the old behavior, migrations need to be changed to instead create a LONGTEXT column without a constraint.
To make use of the new behavior, add the json_valid constraint to according columns on pre-existing databases and remove any JSON serialization/deserialization logic that was used before this change.

[terabytesoftw]

Thanks for the recommendation, it would be great if you could do a PR.

[chriscpty]

Done. I still don't think this is an optimal solution though, seeing as breaking changes are otherwise limited to major or minor, not patch versions (so you don't expect there to be breaking changes going from 2.0.49 to 2.0.50).

[samdark]

I agree that this solution isn't great regarding backwards-compatibility. Thanks for docs pull request. Merged it.