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.
Overview
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.
Source
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:
- create
migration-context.xml
<beans>
<bean id="myDB100To110Migration"
class="org.osaf.cosmo.migrate.BasicSqlScriptMigration">
<property name="fromVersion">
<value>100</value>
</property>
<property name="toVersion">
<value>110</value>
</property>
<property name="supportedDialects">
<set>
<value>MyDB</value>
</set>
</property>
</bean>
</beans>
- create migration scripts that
BasicSqlScriptMigration
looks for:
-
100-to-110-MyDB-pre.sql
-
100-to-110-MyDB-post.sql
- 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
- ensure extension jar is in the working dir when running the migration jar
-- RandyLetness - 09 Jul 2008