DevGuide UpgradeFunctions

MDG: Upgrade Functions

As a plugin evolves, it is not uncommon for a developer to want to fundamentally change the way a plugin stores its data. If the developer cares about backwards compatibility (and we all do right?) then they will often need to have some way to help transition users in a completely seamless manner to the new scheme.

Melody facilitates this process through the use of upgrade functions. Upgrade functions are registered for a specific object class (like "entry," "page" or "author"). Then for each record associated with that class, Melody will pass that record to a function for tweaking and modification. Upgrade functions are also associated with a specific schema version, that way Melody is ensured only to run the function for those users for which the upgrade function is relevant, and only against a specific version of the schema.

Developers can also register raw SQL code to be run against the database if that is easier.

name: Example Plugin for Melody
id: Example
description: This plugin is an example plugin for Melody.
version: 1.2
schema_version: 10
upgrade_functions:
	my_function:
		version_limit: 9
		priority: 1
		updater:
			type: entry
			label: "Doing something to all entries."
			condition: $Example::Example::Plugin::my_upgrade_condition
			code: $Example::Example::Plugin::my_upgrade_function
			sql: $Example::Example::Plugin::my_upgrade_sql

Upgrade Function Registry Properties

• version_limit - the schema version for which this upgrade function should be run against. For example, if a user is upgrading from schema version 5 to 6, then the version limit would be set to 5 indicating that the upgrade function should not be run if the current schema version is greater than 5.
• priority - this is used to determine the order in which a set of upgrade functions should be run. (1 has the highest priority ensure that it will be run first)

Update Registry Properties

• type - the object class for which this upgrade function applies. This also determines the type of the object that will be passed into each of the related handlers.
• label - The text that is displayed to the administrator during the upgrade process to provide some insight into the operation being performed.
• condition - a handler that should return a boolean value, true if the associated upgrade handler should be run, and false otherwise.
• code - a reference to a handler to process each object in the system for which this upgrade function applies.
• sql - a reference to a handler that should return an array of SQL statements that should be run against the database.

Sample Plugin.pm File

Here is a sample set of handlers for each of the registry properties above.

package Example::Plugin;
use strict;

sub my_upgrade_function {
	my ($obj) = @_;
	$obj->some_property('some value');
}

sub my_upgrade_condition {
	my ($obj) = @_;
	return 0 if $obj->title eq "Foo"; # do not upgrade this record
	return 1; # upgrade this record
}

sub my_upgrade_sql {
	return (
      "UPDATE mt_entry SET some_property='xyz' WHERE title='Foo'",
      "UPDATE mt_entry SET some_property='123' WHERE title='Bar'",
	);
}

You should note that in the my_upgrade_function handler, as with all upgrade handlers, there is no need to issue a $obj->save() command with the corresponding object being upgraded. Melody will call the save() method on the object after all the upgrade functions associated with this schema version and this object type have been run.

Continue Reading

• MDG: Custom and Pluggable Rich Text Editors - Melody's ArcheType Framework

 

Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

• Author: Byrne Reese
• Edited by: Violet Bliss Dietz