Caudium :: CreateUpgradeTask


Open Webserver

Quick Info



bug reports: sourcehut

source code: git

twitter: caudiumweb




wiki > CreateUpgradeTask


Thursday, 26 July 2012 by Bill Welliver

Caudium 1.5 includes a revised mechanism for performing tasks when upgrading between versions of Caudium. Previously, the tasks were either run or not run and would only be runnable as a large block. Obviously, when there are a theoretically infinite combination of starting and ending versions, we needed to come up with a better solution.

The Basics

The new upgrade system consists of a method that checks to see if there are upgrade tasks to perform, and if so, runs them. This process runs at server startup.

Tasks to be performed during an upgrade are arranged by version number; that is, the version of Caudium that introduced the compatibility change that must be remedied. This exists in the form of a directory (server/etc/upgrade.d) that contains a directory for each Caudium version for which tasks need to be performed. Inside of that directory are one or more pike programs that conform to Caudium.UpgradeTask.

When the upgrade process runs, it checks the current version of Caudium and compares it to the version previously upgraded to. This is stored in a Global Variable, and can, if necessary, be reset in order to force upgrade steps to be re-performed. The upgrade process then performs the upgrade tasks for each version in order, updating the version upgraded to after successful completion of each set up tasks. This ensures that in the event of an error during upgrade, steps will not be marked as completed without having actually succeeded.

Informative information is printed at each stage of the upgrade process to the default debug log (logs/debug/default.1)

Creating a new Upgrade Task

To create a new upgrade task, create a directory for the version of Caudium introducing the change, such as 1.5.0. Inside that directory, create a pike program that inherits Caudium.UpgradeTask.

In order for your upgrade task to do something, you should implement either upgrade_configuration() or upgrade_server(). upgrade_configuration() is used to perform changes for each virtual server defined, such as would be needed if a module were changed significantly. This function is called once for each virtual server and receives the configuration object to be upgraded. An example task using this method is found in 1.4.0/userdb.pike. upgrade_server() is used for tasks that apply to the server installation as a whole. This method is called once for each upgrade task. An example task using this method is found in 1.5.0/config_interface.pike.

Note that an upgrade task may be forced to run, so you should not assume that a task has not already been performed.

No comments | Post a Comment | RSS Feed | BackLinks |