From time to time, it is necessary to make changes that require some processing beyond just manipulating the database schema. For example, it may be necessary to change the values of existing records, or populate default values for some new attribute. Where possible, automate these changes using the UpgradeVersionShell. (There may still be times when manual intervention is required. Continue to document those steps in the wiki on version specific pages.)
Current vs Target
The current version is defined as the contents of cm_meta:upgrade_version
.
The target version is defined as the contents of the file Config/VERSION
.
$versions
Each new release must have an entry in the UpgradeVersionShell::$versions
array. The key is the version number and the value is an array with the following supported entries:
block
: (Required) Boolean indicating whether or not this version blocks future versions in a single upgrade. See below.pre
: (Optional) The name of a function (defined withinUpgradeVersionShell
) to be called before the database schema is updated. While any name can be used, in general follow the formatpre094
, replacing094
with the appropriate version.post
: (Optional) The name of a function (defined withinUpgradeVersionShell
) to be called after the database schema is updated. While any name can be used, in general follow the formatpost094
, replacing094
with the appropriate version.
Blocking
When the database schema is updated, it always bring the schema up to the latest version. Currently, schemas are not explicitly attached to releases. UpgradeVersionShell, however, can run pre and post upgrade scripts on a per-version basis. This creates a problem if, for example, a change is introduced in v1.1.0 that requires manual intervention, and an administrator attempts to upgrade directly from v1.0.0 to v1.2.0.
The solution is to flag v1.1.0 as blocking, using the block
keyword described above. When true, UpgradeVersionShell will prevent upgrading past v1.1.0 until the current version is v1.1.0.
If you flag a version as blocking, be sure to document why. This is currently done in UpgradeVersionShell.php
.