Tricia Help
Last edited Oct 28, 2011
Tags: no tags assigned  

Class SchemaMigrationDoc

in package de.infoasset.platform.documentation

Declaration
public class SchemaMigrationDoc
extends Object
Hierarchy
java.lang.Object
  extendsde.infoasset.platform.documentation.SchemaMigrationDoc

Schema Migration

Developing Tricia further inevitably leads to changes to the data model, which have to be applied to existing productive installations. This problem is called schema migration.

There are two different aspects of schema migration:

  1. altering the layout of the Store, e.g. adding or removing tables or columns, and
  2. semantic migration of the data, e.g. changing the serialization representation from XML to JSON.
    3. .
Both aspects will be discussed independently of each other in the following.

Store Migration

On startup and during the update of a production system the database schema is compared against the current data model defined in the Java code. This check is only applied if Tricia runs in a mode which is a subclass of ProductionMode.

If there are differences, Tricia tries to handle them. There are two different kinds of store migration steps:

  • Safe migration steps (adding columns, creating and removing indices) are taken automatically, the system executes the necessary SQL command automatically on startup.
  • For unsafe migration steps (removing columns and tables) the SQL commands are generated and have to be executed by the administrator manually.

Data Migration

Data migrations are specified by implementing a subclass of the extension point MigrationStep. The following code example shows a migration step which sets the property properties to the value <Diffs/> for all entities of type EntityDiff, which have a type property with the value _new: 
 
 @Override
 
 public class CorePlugin extends Plugin {
     ...
 
     final MigrationStep removeEventsForNewEntities = new MigrationStep() {
 
         @Override
         public String getRelease() {
             return "3.1.11";
         }
 
         @Override
         public void action() {
             Container c = Store.INSTANCE().getContainer("entitydiff_");
             StringAttribute typeAttr = (StringAttribute) c.getContentType().getAttribute("type");
             StringAttribute propertiesAttr = (StringAttribute) c.getContentType().getAttribute("properties");
             Iterator it = c.queryContentIds(new QueryEquals(typeAttr, "_new"), -1, null);
             while (it.hasNext()) {
                 String id = it.next();
                 Content content = c.getContent(id);
                 content.setString(propertiesAttr, "");
                 content.write();
                 Store.INSTANCE().commit();
             }
         }
 ...
The return value of the method MigrationStep.getRelease() is used only for determining the order in which the migration steps are applied.

A migration step has to have the following properties:

  • Each step has to be idempotent, which means that it can be applied multiple times without changing the result.
  • Each step is not allowed to affect the behaviour of an installation which runs on the very same data store.

Milestone Releases

In some cases it is necessary to enforce the update to a specific release before updating to newer releases is possible. These releases which cannot be skipped are called milestone releases. In the source code a milestone release is specified by implementing an extension point of type MilestoneRelease: 
 final MilestoneRelease changedMigration = new MilestoneRelease() {
 
     @Override
     public boolean isCurrentRelease() {
         return true;
     }
 
     @Override
     public String getRelease() {
         return "3.1.15";
     }
 };
The method MilestoneRelease.isCurrentRelease() indicates that this is the milestone release. In the releases following the milestone release, this method has to be implemented returning false.

Schema Migration Mode

There is a special run mode, which is called schema-migration mode (see SchemaMigrationDoc), which initialized the system, checks for migration steps and then stops executing after this check. Tricia is started in this run mode if a production system is updated to a newer version.

Updating Tricia

When a productive Tricia instance is updated to a newer release, migration is done automatically triggered by the Installer. The following steps take place while the old version is running:
  1. The new software is pulled from the repository, a copy is created.
  2. The existing configuration is checked against the new software.
  3. The software is compiled.
  4. If there is a running system in parallel:
    1. A system message is applied which says, that an update will occur in 5 minutes.
    2. After 5 minutes the system is set in read-only mode.
    3. The new software is started in SchemaMigrationMode, all migration steps are applied while the old version is running in read-only mode.
    4. If migration was successful:
      1. The new software is registered in wrapper.conf.
      2. The system is restarted.
      If not:
      1. Read-only mode is disabled.
    If not:
    1. The new software is started in SchemaMigrationMode, all migration steps are applied.
    2. If migration was successful, the new software is registered in wrapper.conf.

Constructor Summary

SchemaMigrationDoc()

Constructor Detail

SchemaMigrationDoc

public SchemaMigrationDoc()

0 Comments