Difference between revisions of "AppSuite:DBMigration"
(→Important hints) |
|||
| Line 69: | Line 69: | ||
== Important hints == | == Important hints == | ||
| − | * | + | * ChangeSets are executed top-down within a ChangeLog, so always add new migrations at the bottom of the file. For migrations regarding core components always use the configdbChangeLog.xml in com.openexchange.database.migration/resource/liquibase. For non-core components see [[AppSuite:CustomDBMigration]]. |
| − | * if you would like to use <include> statements to reference other files with Liquibase statements we suggest adding parameter 'relativeToChangelogFile="true"' to avoid adding complete paths. | + | * ChangeSets must be constructed in an idempotent manner, i.e. they must not fail or break something if they are run several times. Use preconditions with onFail="MARK_RAN" to achieve this. |
| + | * If you are adding the first migration for an upcoming release, add an according milestone tag before the actual migration ChangeSets! | ||
| + | * If you would like to use <include> statements to reference other files with Liquibase statements we suggest adding parameter 'relativeToChangelogFile="true"' to avoid adding complete paths. | ||
* http://www.liquibase.org/documentation/sql_output.html | * http://www.liquibase.org/documentation/sql_output.html | ||
Revision as of 11:19, 9 September 2014
Summary: With release 7.6.1 it is possible to change the database schema based on usage of the open source tool Liquibase. Currently only updating the configdb with the new mechanism is desired. This article gives a short introduction about the current implementation
Please have a look at Liquibase, its features and documentation before working with database migrations for Open-Xchange server: http://www.liquibase.org/documentation/ .
Ho to create custom bundles is explained in an extra article: http://oxpedia.org/wiki/index.php?title=AppSuite:CustomDBMigration
Contents
Database migration bundles
The following bundles provide the functionality for executing database migration statements. All are included within the open-xchange-core package.
- com.openexchange.database.migration: Provides the service to execute database migrations
- com.openexchange.database.migration.ox: Provides the database migration statements relevant for the Open-Xchange server
- com.openexchange.database.migration.clt: Provides some command line tools that might help by working with database migration based on Liquibase
Current restrictions
- Database migrations can only be applied to the configdb!
- Open-Xchange server currently uses Liquibase version 3.0.7. All features provided with later versions cannot be used.
Liquibase
The following chapter describes shortly the Liquibase features and how they are used by Open-Xchange. For further information have a look at the official Liquibase documentation: http://www.liquibase.org/documentation/
ChangeLog file / changeSets
A ChangeLog file is the heart of this database migration and contains all information required to change database structure and/or contents. It consists of ChangeSets that are used to define a migration. Normally ChangeSets are executed transactionally.
Tags
A ChangeSet can be used to tag the database at a current state. Open-Xchange uses this mechanism to tag the database to be ready for a new release.
Preconditions
Preconditions can be used to define dependencies between ChangeSets. You can attach another ChangeSet to whatever ChangeSet you would like to. This will only be executed if the prior was executed successfully. You can create complex conditions by using nested conditions that have to be true to execute the ChangeSet with the precondition.
Open-Xchange uses preconditions for instance for ChangeSets that should be executed after the database has been tagged for a new release. All ChangeSets after tagging checks if the precondition is true.
For further information about that complex function have a look at the following documentation: http://www.liquibase.org/documentation/preconditions.html
Database
Database tables
Liquibase creates two tables to handle its current state:
- LIQUIBASECHANGELOG: Contains information about the execution status of ChangeSets. Each executed ChangeSet will be added to this table. If there is no entry available for a ChangeSet Liquibase will try to execute the statement.
- LIQUIBASECHANGELOGLOCK: Handles access to the database to not execute database migration statements twice.
Database lock
Liquibase uses a lock to only grant one Liquibase instace access to the database to change. For this purpose a table named 'DATABASECHANGELOGLOCK' is created. In cluster environments the first node that successfully aquired the lock will execute the database migration statements. During this time all other nodes are blocked. After the lock was released the second node will get access to the database and read already executed ChangeSets. If all ChangeSets have been executed nothing will be done and the lock will be released. This happens with each node within the cluster.
Custom Java Classes
Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements.
Command line tools
Currently the following command line tools are available (in bundle com.openexchange.database.migration.clt):
- /opt/open-xchange/sbin/forcedbmigration: Tries to force the migration for the file provided within the parameters.
- /opt/open-xchange/sbin/listunexecutedchangesets: Lists currently unexecuted changesets for the file provided within the parameters.
- /opt/open-xchange/sbin/releasedbmigrationlock: Tries to release the database lock so that Liquibase is able to acquire the lock again. Not releasing the lock might happen when the server was shut down while startup. Using this command line tool includes that com.openexchange.database.migration bundle is running. If it does not get up please execute
<code>UPDATE DATABASECHANGELOGLOCK SET LOCKED=0, LOCKGRANTED=null, LOCKEDBY=null where ID=1;</code>
- /opt/open-xchange/sbin/rollbackdbmigration: Execute a rollback to the provided database tag. Rollbacks have to be defined for each ChangeSet as for most change statements no autorollback is supported.
Important hints
- ChangeSets are executed top-down within a ChangeLog, so always add new migrations at the bottom of the file. For migrations regarding core components always use the configdbChangeLog.xml in com.openexchange.database.migration/resource/liquibase. For non-core components see AppSuite:CustomDBMigration.
- ChangeSets must be constructed in an idempotent manner, i.e. they must not fail or break something if they are run several times. Use preconditions with onFail="MARK_RAN" to achieve this.
- If you are adding the first migration for an upcoming release, add an according milestone tag before the actual migration ChangeSets!
- If you would like to use <include> statements to reference other files with Liquibase statements we suggest adding parameter 'relativeToChangelogFile="true"' to avoid adding complete paths.
- http://www.liquibase.org/documentation/sql_output.html