AppSuite:DBMigration - Revision history

Martin.schneider: /* Database tables */

2019-03-14T10:03:12Z

Database tables

← Older revision		Revision as of 10:03, 14 March 2019
Line 36:		Line 36:
	Liquibase creates two tables to handle its current state:		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.		* DATABASECHANGELOG: 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.		* DATABASECHANGELOGLOCK: Handles access to the database to not execute database migration statements twice.

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

Tobias.friedrich at 09:38, 19 June 2015

2015-06-19T09:38:18Z

← Older revision		Revision as of 09:38, 19 June 2015
Line 5:		Line 5:
	<div class="title">Database migration for Open-Xchange server.</div>		<div class="title">Database migration for Open-Xchange server.</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 about the current implementation		'''Summary''': With release 7.6.1 it is possible to change the database schema based on usage of the open source tool Liquibase. Currently this applies to the config database, as well as so-called global databases for storing cross-context data (available with v7.8). 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/ and http://www.liquibase.org/bestpractices.html .		Please have a look at Liquibase, its features and documentation before working with database migrations for Open-Xchange server: http://www.liquibase.org/documentation/ and http://www.liquibase.org/bestpractices.html .
Line 16:		Line 16:
	The following bundles provide the functionality for executing database migration statements. All are included within the open-xchange-core package.		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 and the core ~~configdb ChangeLog~~		* com.openexchange.database.migration: Provides the service to execute database migrations and the core database ChangeLogs
	* com.openexchange.database.migration.clt: Provides a command line tool that might help by working with database migrations based on Liquibase		* com.openexchange.database.migration.clt: Provides a command line tool that might help by working with database migrations based on Liquibase

	== Current restrictions ==		== 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.		* Open-Xchange server currently uses Liquibase version 3.0.7. All features provided with later versions cannot be used.

Line 53:		Line 52:

	== Command line tool ==		== Command line tool ==
	Currently a command line tools is provided to manage the ~~core configdb~~ migrations: ''/opt/open-xchange/sbin/dbmigrations'' (Note: in versions prior v7.8, the utitlity is named ''configdbmigrations'', and the ''name'' option is missing):		Currently a command line tools is provided to manage the migrations: ''/opt/open-xchange/sbin/dbmigrations'' (Note: in versions prior v7.8, the utitlity is named ''configdbmigrations'', and the ''name'' option is missing):

	usage: dbmigrations		usage: dbmigrations

Tobias.friedrich: /* Command line tool */

2015-06-19T09:35:38Z

Command line tool

← Older revision		Revision as of 09:35, 19 June 2015
Line 53:		Line 53:

	== Command line tool ==		== Command line tool ==
	Currently a command line tools is provided to manage the core configdb migrations: /opt/open-xchange/sbin/configdbmigrations		Currently a command line tools is provided to manage the core configdb migrations: ''/opt/open-xchange/sbin/dbmigrations'' (Note: in versions prior v7.8, the utitlity is named ''configdbmigrations'', and the ''name'' option is missing):

	usage: ~~configdbmigrations~~		usage: dbmigrations
	-A,--adminuser <arg> Admin username		-A,--adminuser <arg> Admin username
	-h,--help Prints a help text		-h,--help Prints a help text
	-l,--login <arg> The optional JMX login (if JMX authentication is		-l,--login <arg> The optional JMX login (if JMX
	enabled)		authentication is enabled)
	-ll,--list-locks Lists all currently acquired locks.		-ll,--list-locks Lists all currently acquired locks.
	-P,--adminpass <arg> Admin password		-n,--name <arg> The database schema name to use
	-p,--port <arg> The optional JMX port (default:9999)		-P,--adminpass <arg> Admin password
	-r,--run Forces a run of the current core changelog.		-p,--port <arg> The optional JMX port (default:9999)
	-s,--password <arg> The optional JMX password (if JMX authentication		-r,--run Forces a run of the current core changelog.
	is enabled)		--responsetimeout <arg> The optional response timeout in seconds
	-u,--force-unlock Forces a release of all locks.		when reading data from server (default: 0s;
			infinite)
			-s,--password <arg> The optional JMX password (if JMX
			authentication is enabled)
			-t,--host <arg> The optional JMX host (default:localhost)
			-u,--force-unlock Forces a release of all locks.
	Prints the current migration status if no option is set.		Prints the current migration status if no option is set.

Martin.schneider at 07:05, 12 May 2015

2015-05-12T07:05:43Z

← Older revision		Revision as of 07:05, 12 May 2015
Line 47:		Line 47:

	Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements.		Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements.

			== Implementation details ==

			The Open-Xchange server will wait within the startup until all provided Liquibase update tasks have been executed to ensure consistent data usage!

	== Command line tool ==		== Command line tool ==

Thorben at 16:00, 27 January 2015

2015-01-27T16:00:52Z

← Older revision		Revision as of 16:00, 27 January 2015
Line 7:		Line 7:
	'''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		'''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/ .		Please have a look at Liquibase, its features and documentation before working with database migrations for Open-Xchange server: http://www.liquibase.org/documentation/ and http://www.liquibase.org/bestpractices.html .

	Ho to create custom bundles is explained in an extra article: http://oxpedia.org/wiki/index.php?title=AppSuite:CustomDBMigration		Ho to create custom bundles is explained in an extra article: http://oxpedia.org/wiki/index.php?title=AppSuite:CustomDBMigration

Martin.schneider: /* Important hints */

2015-01-20T14:40:55Z

Important hints

← Older revision		Revision as of 14:40, 20 January 2015
Line 68:		Line 68:
	* 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 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.		* 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 are adding the first migration for an upcoming release, add an according milestone tag after 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.		* 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

Steffen.templin: /* Command line tools */

2014-09-09T11:42:34Z

Command line tools

← Older revision		Revision as of 11:42, 9 September 2014
Line 48:		Line 48:
	Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements.		Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements.

	== Command line ~~tools~~ ==		== Command line tool ==
	Currently ~~the following~~ command line tools ~~are available (in bundle com.openexchange.database.migration.clt)~~:		Currently a command line tools is provided to manage the core configdb migrations: /opt/open-xchange/sbin/configdbmigrations

	* /opt/open-~~xchange/sbin/forcedbmigration: Tries to force the migration for the file provided within the parameters.~~		usage: configdbmigrations
			-A,--adminuser <arg> Admin username
	* /opt/open-~~xchange/sbin/listunexecutedchangesets:~~ Lists currently ~~unexecuted changesets for the file provided within the parameters~~.		-h,--help Prints a help text
			-l,--login <arg> The optional JMX login (if JMX authentication is
	* /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~~		enabled)
	~~<pre><code>UPDATE DATABASECHANGELOGLOCK SET LOCKED=0~~, ~~LOCKGRANTED=null, LOCKEDBY=null where ID=1;~~<~~/code></pre~~>		-ll,--list-locks Lists all currently acquired locks.
			-P,--adminpass <arg> Admin password
	* /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~~.		-p,--port <arg> The optional JMX port (default:9999)
			-r,--run Forces a run of the current core changelog.
			-s,--password <arg> The optional JMX password (if JMX authentication
			is enabled)
			-u,--force-unlock Forces a release of all locks.
			Prints the current migration status if no option is set.

	== Important hints ==		== Important hints ==

Steffen.templin: /* Preconditions */

2014-09-09T11:39:55Z

Preconditions

← Older revision		Revision as of 11:39, 9 September 2014
Line 31:		Line 31:
	=== 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.

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

Steffen.templin: /* Database migration bundles */

2014-09-09T11:39:04Z

Database migration bundles

← Older revision		Revision as of 11:39, 9 September 2014
Line 16:		Line 16:
	The following bundles provide the functionality for executing database migration statements. All are included within the open-xchange-core package.		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: Provides the service to execute database migrations and the core configdb ChangeLog
	* com.openexchange.database.migration.ox: Provides the database migration statements relevant for the ~~Open-Xchange server~~		* com.openexchange.database.migration.clt: Provides a command line tool that might help by working with database migrations based on Liquibase
	* com.openexchange.database.migration.clt: Provides ~~some~~ command line ~~tools~~ that might help by working with database ~~migration~~ based on Liquibase

	== Current restrictions ==		== Current restrictions ==

Steffen.templin: /* Important hints */

2014-09-09T11:19:14Z

Important hints

← Older revision		Revision as of 11:19, 9 September 2014
Line 69:		Line 69:

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