AppSuite:CustomDBMigrationBundle - Revision history

Martin.schneider: Blanked the page

2014-08-28T16:58:10Z

Blanked the page

← Older revision		Revision as of 16:58, 28 August 2014
Line 1:		Line 1:
	~~{{VersionFrom\|7.6.1}}~~

	~~<div class="title">How to write custom bundles to execute database migration statements.</div>~~

	'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.

	~~Please have a look at liquibase, its features and documentation before writing custom bundles: http://www.liquibase.org/documentation/ .~~

	~~__TOC__~~

	~~== Prerequisite ==~~
	~~This article is based on an existing sample bundle located in the public git repository backend-samples. Clone the repository by executing~~

	~~<code><pre>~~
	~~git clone https://git.open-xchange.com/git/examples/backend-samples~~
	~~</pre></code>~~

	~~The required bundle is named 'com.openexchange.sample.database.migration'.~~

	~~== 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.

	~~== Bundle dependencies ==~~
	To execute custom database migration for the configdb you have to track the service com.openexchange.database.migration.DBMigrationExecutorService (default provided within bundle com.openexchange.database.migration).

	If you would like to have the Open-Xchange database migrations executed before your custom statements are used you even have to track the service com.openexchange.database.migration.ox.DBMigrationOXExcecutorService which is provided within the bundle com.openexchange.database.migration.ox

	~~Usage of both is shown within the sample bundle.~~

	~~== Liquibase ==~~
	The following chapter describes in short 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.

	~~You have to provide a ChangeLog file that contains some ChangeSets that reflect your desired database migration. Within the sample bundle the file 'custom.changelog.xml' is referenced.~~

	~~=== 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.~~

	~~Tags are not used in the sample custom bundle.~~

	~~=== Preconditions ===~~
	You are even able to define dependencies between ChangeSets. With that you can attach your custom ChangeSet to whatever ChangeSet you would like to. Open-Xchange uses this 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. You can create complex conditions by using nested conditions. For further information have a look at the following documentation: http://www.liquibase.org/documentation/preconditions.html

	Within the custom bundle the precondition is defined as follows: the changeSet with id="7.6.1:login2context:login_info", author="martin.schneider" and changeLogFile="release-7.6.1/1.login_info.changelog.xml" have to be executed (defined in ox.changelog.xml) so that all changeSets within custom.changelog.xml will become executed.

	~~=== 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 ===~~

	~~Within your custom ChangeLog xml file you are not only able to define changes descriptive but even execute database statements defined within a class that implements CustomSqlChange.~~

	~~Have a look at the sample bundle which references and executes com.openexchange.sample.database.migration.custom.ExampleCustomSqlChange.~~

	~~== Command line tools ==~~

	~~== Important hints ==~~
	* changeSets are uniquely identified by its id, author and path. Use the parameter 'logicalFilePath' for every changeSet you create to set a path that can be globally identified! If you do not set a logical file path liquibase will use the physical path of the file the changeSet is located in. With that each changeSet on different cluster nodes might have been identified as a new one.
	* 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.

	~~[[Category: OX7]]~~
	~~[[Category: AppSuite]]~~
	~~[[Category: Administrator]]~~
	~~[[Category: Database]]~~

Martin.schneider: /* Important hints */

2014-08-28T12:49:24Z

Important hints

← Older revision		Revision as of 12:49, 28 August 2014
Line 68:		Line 68:

	== Important hints ==		== Important hints ==
			* changeSets are uniquely identified by its id, author and path. Use the parameter 'logicalFilePath' for every changeSet you create to set a path that can be globally identified! If you do not set a logical file path liquibase will use the physical path of the file the changeSet is located in. With that each changeSet on different cluster nodes might have been identified as a new one.
			* 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.

	[[Category: OX7]]		[[Category: OX7]]

Martin.schneider at 12:35, 28 August 2014

2014-08-28T12:35:51Z

← Older revision		Revision as of 12:35, 28 August 2014
Line 1:		Line 1:
	{{~~Version~~\|7.6.1}}		{{VersionFrom\|7.6.1}}

	<div class="title">How to write custom bundles to execute database migration statements.</div>		<div class="title">How to write custom bundles to execute database migration statements.</div>
Line 5:		Line 5:
	'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.		'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.

	Please have a look at liquibase, its features and documentation before writing custom bundles: http://www.liquibase.org/documentation/ ~~. Current available version of liquibase within the Open-Xchange server is 3.0.7~~.		Please have a look at liquibase, its features and documentation before writing custom bundles: http://www.liquibase.org/documentation/ .

	__TOC__		__TOC__
Line 20:		Line 20:
	== Current restrictions ==		== Current restrictions ==
	* Database migrations can only be applied to the configdb!		* 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.

	== Bundle dependencies ==		== Bundle dependencies ==

Martin.schneider at 12:32, 28 August 2014

2014-08-28T12:32:13Z

← Older revision		Revision as of 12:32, 28 August 2014
Line 1:		Line 1:
			{{Version\|7.6.1}}

	<div class="title">How to write custom bundles to execute database migration statements.</div>		<div class="title">How to write custom bundles to execute database migration statements.</div>

Martin.schneider: /* Database tables */

2014-08-28T12:30:32Z

Database tables

← Older revision		Revision as of 12:30, 28 August 2014
Line 47:		Line 47:

	==== Database tables ====		==== Database tables ====
	Liquibase creates two tables to ~~persist the~~ current ~~status~~:		Liquibase creates two tables to handle its current state:

	* LIQUIBASECHANGELOG: Contains information about the execution 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.		* 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.		* LIQUIBASECHANGELOGLOCK: Handles access to the database to not execute database migration statements twice.

Martin.schneider: /* Liquibase */

2014-08-28T12:28:22Z

Liquibase

← Older revision		Revision as of 12:28, 28 August 2014
Line 27:		Line 27:

	== Liquibase ==		== Liquibase ==
	The following chapter describes in short the liquibase features used. For ~~furhter~~ information have a look at the official liquibase documentation: http://www.liquibase.org/documentation/		The following chapter describes in short 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 ===		=== 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.		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.

			You have to provide a ChangeLog file that contains some ChangeSets that reflect your desired database migration. Within the sample bundle the file 'custom.changelog.xml' is referenced.

	=== Tags ===		=== 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.		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.

			Tags are not used in the sample custom bundle.

	=== Preconditions ===		=== Preconditions ===
	You are even able to define dependencies between ChangeSets. With that you can attach your custom ChangeSet to whatever ChangeSet you would like to. Open-Xchange uses this 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. You can create complex conditions by using nested conditions. For further information have a look at the following documentation: http://www.liquibase.org/documentation/preconditions.html		You are even able to define dependencies between ChangeSets. With that you can attach your custom ChangeSet to whatever ChangeSet you would like to. Open-Xchange uses this 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. You can create complex conditions by using nested conditions. For further information have a look at the following documentation: http://www.liquibase.org/documentation/preconditions.html

			Within the custom bundle the precondition is defined as follows: the changeSet with id="7.6.1:login2context:login_info", author="martin.schneider" and changeLogFile="release-7.6.1/1.login_info.changelog.xml" have to be executed (defined in ox.changelog.xml) so that all changeSets within custom.changelog.xml will become executed.

	=== Database ===		=== Database ===
Line 52:		Line 58:
	=== Custom Java Classes ===		=== Custom Java Classes ===

	Within your custom ChangeLog xml file you are not only able to define changes descriptive but even execute database statements defined within a class that implements CustomSqlChange. Have a look at the sample bundle which references and executes com.openexchange.sample.database.migration.custom.ExampleCustomSqlChange.		Within your custom ChangeLog xml file you are not only able to define changes descriptive but even execute database statements defined within a class that implements CustomSqlChange.

			Have a look at the sample bundle which references and executes com.openexchange.sample.database.migration.custom.ExampleCustomSqlChange.

	== Command line tools ==		== Command line tools ==

Martin.schneider at 11:46, 28 August 2014

2014-08-28T11:46:11Z

← Older revision		Revision as of 11:46, 28 August 2014
Line 17:		Line 17:

	== Current restrictions ==		== Current restrictions ==
	Database migrations can only be applied to the configdb!		* Database migrations can only be applied to the configdb!

	== Bundle dependencies ==		== Bundle dependencies ==
Line 26:		Line 26:
	Usage of both is shown within the sample bundle.		Usage of both is shown within the sample bundle.

	== ~~Using~~ Liquibase ==		== Liquibase ==
			The following chapter describes in short the liquibase features used. For furhter information have a look at the official liquibase documentation: http://www.liquibase.org/documentation/

	=== ~~Database lock~~ ===		=== 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 ===
			You are even able to define dependencies between ChangeSets. With that you can attach your custom ChangeSet to whatever ChangeSet you would like to. Open-Xchange uses this 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. You can create complex conditions by using nested conditions. For further information have a look at the following documentation: http://www.liquibase.org/documentation/preconditions.html

			=== Database ===

			==== Database tables ====
			Liquibase creates two tables to persist the current status:

			* LIQUIBASECHANGELOG: Contains information about the execution 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 ===		=== Custom Java Classes ===

			Within your custom ChangeLog xml file you are not only able to define changes descriptive but even execute database statements defined within a class that implements CustomSqlChange. Have a look at the sample bundle which references and executes com.openexchange.sample.database.migration.custom.ExampleCustomSqlChange.

	== Command line tools ==		== Command line tools ==

Martin.schneider at 10:26, 28 August 2014

2014-08-28T10:26:07Z

← Older revision		Revision as of 10:26, 28 August 2014
Line 2:		Line 2:

	'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.		'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.

			Please have a look at liquibase, its features and documentation before writing custom bundles: http://www.liquibase.org/documentation/ . Current available version of liquibase within the Open-Xchange server is 3.0.7.

	__TOC__		__TOC__
Line 13:		Line 15:

	The required bundle is named 'com.openexchange.sample.database.migration'.		The required bundle is named 'com.openexchange.sample.database.migration'.

			== Current restrictions ==
			Database migrations can only be applied to the configdb!

	== Bundle dependencies ==		== Bundle dependencies ==
			To execute custom database migration for the configdb you have to track the service com.openexchange.database.migration.DBMigrationExecutorService (default provided within bundle com.openexchange.database.migration).

			If you would like to have the Open-Xchange database migrations executed before your custom statements are used you even have to track the service com.openexchange.database.migration.ox.DBMigrationOXExcecutorService which is provided within the bundle com.openexchange.database.migration.ox

			Usage of both is shown within the sample bundle.

	== Using Liquibase ==		== Using Liquibase ==

	== Database lock ==		=== Database lock ===

	=== Preconditions ===		=== Preconditions ===

Martin.schneider: Created page with "
How to write custom bundles to execute database migration statements.
'''Summary''': With release 7.6.1 it is possible to change the database schema ..."

2014-08-26T14:32:25Z

Created page with "<div class="title">How to write custom bundles to execute database migration statements.</div> '''Summary''': With release 7.6.1 it is possible to change the database schema ..."

New page

<div class="title">How to write custom bundles to execute database migration statements.</div>

'''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 based on an existing sample bundle how to write custom database migration bundles and how to attach your custom statements to those given by Open-Xchange.

__TOC__

== Prerequisite ==
This article is based on an existing sample bundle located in the public git repository backend-samples. Clone the repository by executing

<code><pre>
git clone https://git.open-xchange.com/git/examples/backend-samples
</pre></code>

The required bundle is named 'com.openexchange.sample.database.migration'.

== Bundle dependencies ==

== Using Liquibase ==

== Database lock ==

=== Preconditions ===

=== Custom Java Classes ===

== Command line tools ==

== Important hints ==

[[Category: OX7]]
[[Category: AppSuite]]
[[Category: Administrator]]
[[Category: Database]]