r1 - 09 Jul 2008 - 15:10:19 - RandyLetnessYou are here: OSAF >  Documentation Web  >  ServerBundleAdministrator > ServerBundleInstallation > CosmoMigrationDevelopers

Cosmo Migration Information for Developers

This page contains information about the migration code included with the server bundle that allows users to migrate existing data from an older version of the server to the latest version.


The server bundle includes a migration component located in $OSAFSRV_HOME/migration, which consists of a self-contained jar, a README file and migration.properties file.

File purpose
migration.jar self-containted jar containing all code and migration code and scripts
README.txt instructions on how to perform migration
migration.properties sample properties file that contains properties required for migration.

In a nutshell, the migration component is a java program designed to migrate from any previous version the the server to the latest version. The component is updated for each release of the server that contains a schema change.


The source to the migration component is located in the migration subdir of the root cosmo tree. See ChandlerServerSource? for information on checking out the cosmo source.

Source layout:

  • src/main/java - java source files
  • src/main/resources resource files including spring configuration files, sql scripts
  • src/test - unit test source + resources
  • src/main/config - sample migration properties
  • src/docs - docs

Building Migration Component

To build the all-in-one jar:
  • cd $COSMO_SRC_ROOT/migration
  • mvn package
This will result in a migration.jar located in the dist subdir.

Migration Manager Overview

The MigrationManger class is the center of the migration component. It is responsible for managing many different Migration implementations and figuring out which Migration=s to run.  A =Migration is an interface describing a database migration. There is a Migration instance for each supported database and schema version, and the MigrationManger queries the current database schema to determine which Migrations to run and in what order.

The migration manager is configured in migrationManager-context.xml and all Migration instances are configured in migration-context.xml.

Main.java reads properties from migration.properties and invokes the MigrationManager.

Adding a new Migration

Adding new migrations can be done in a couple of ways.

Adding to Existing source

  • Define new Migration implementation(s) and add to source (if necessary, otherwise you may be able to re-use existing implementation like BasicSqlScriptMigration)
  • Configure new Migration implementation(s) in migration-context.xml
  • rebuild migration all-in-one jar

Adding using separate Jar

The migration runner also supports loading migrations from separate jar files. It assumes the following:
  • the jar file name contains the text migration-extension
  • the jar file is located in the current working directory
  • the jar file contains a migration-context.xml spring configuration file that defines one or more Migration instances

So for example to create an extension jar to support a simple MyDB? migration from schema ver 100 to 110:

  1. create migration-context.xml
   <bean id="myDB100To110Migration"
        <property name="fromVersion">
        <property name="toVersion">
        <property name="supportedDialects">

  1. create migration scripts that BasicSqlScriptMigration looks for:
    • 100-to-110-MyDB-pre.sql
    • 100-to-110-MyDB-post.sql

  1. create migration-extention-MyDB-100-110.jar that looks like:
    • /migration-context.xml
    • /100-to-110-MyDB-pre.sql
    • /100-to-110-MyDB-post.sql

  1. ensure extension jar is in the working dir when running the migration jar

-- RandyLetness - 09 Jul 2008

Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r1 | More topic actions
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.