How to write a patch task

SQL script patch task

A script patch is written in SQL.
The challenge with SQL patch is the cross database support. If a SQL patch uses a specific database construct it is forcing to duplication the patch for all other databases. Hence we discourage heavily this type of migration script. Instead use a java class patch task using DBSchemaMigrater class.

Do not use any database specific constructs. If you need than write a java class patch task instead that uses DBSchemaMigrater or standard jdbc access.

Java class patch task

Java class patch uses direct jdbc access to manipulate the database.
The direct use of business objects through hibernate is strongly discourage in patch tasks. As the model changes it may be difficult to maintain old migration scripts that might rely on a old definition or mapping of an object. It is safer to go raw jdbc and manipulate the data through private constructs.

Do not use business object or hibernate in patch tasks. Instead go JDBC directly and create the necessary constructs for the task at hand

A base class has already been created to handle most of the plumbing for you: JdbcMigrationTaskSupport.
This class provides a spring JdbcTemplate and a DBSchemaMigrater for you to use to change both database data and schema

Use JdbcMigrationTaskSupport to implement your migration tasks

3 methods may be overriden (1 is required):

• migration(): this is the main entry point to implement your migration
• setUp():anything that must happen before migration() is called with the template and migrater initialized
• tearDown():anything that must happen after the migration even if the migration failed

Another base class is provided to use hibernate and the business objects HibernateMigrationSupport. It has a similar contract as JdbcMigrationTaskSupport but provide access to a hibernate Session.
As mentioned before this class must be used with caution since later change in the business model will require us to maintain old migration tasks that may be affected by these changes.

Cross-database schema migration

DBSchemaMigrater is a class that may be used to manipulate a database schema in a database neutral way. As of 0.7 only mysql and hsqldb are supported. However the architecture is simple and one simple extension of a class allows to supply all database refactoring used in the migration tasks.

When extending DBSchemaMigrater, make sure you add the necessary tests in DBSchemaMigraterTestScript in order to facilitate cross-database testing. Always provide support for the Offically supported databases