Package rife.database.migrations

Class DbMigrations

java.lang.Object

rife.database.migrations.DbMigrations

public class DbMigrations
extends Object

Executes an explicitly registered series of migrations against a datasource.

You register the migrations by hand with strictly increasing version numbers, since nothing is ever discovered or executed implicitly:

var migrations = new DbMigrations(datasource)
    .state(DatabaseResourcesFactory.instance(datasource))
    .add(1, new CreateInitialSchema())
    .add(2, new AddUserTotals());
migrations.migrate();

The current version is stored as the content of a resource through ResourceFinder and ResourceWriter. You can use DatabaseResources to store it in the same database, which has to be installed explicitly beforehand, or DirectoryResources to store it as a plain file. The resource name defaults to RifeConfig.MigrationsConfig.DEFAULT_STATE_RESOURCE and can be changed through RifeConfig.migrations() or per instance.

The methods with a From suffix don't use the stored version at all. The current version is passed in as an argument and the new one is returned, which leaves the storing of it up to you.

Each migration executes inside a transaction together with its state update. Note that not every database is able to roll back DDL, where that isn't supported a failed migration can leave part of its schema changes behind while the version stays unchanged.

Migrations are meant to be run as an explicit operation from a single place, since concurrent migrate calls from several application instances against the same database aren't coordinated in any way.

Since:

1.10

See Also:

• DbMigration
• ReversibleDbMigration

Constructor Summary

Constructors

Constructor	Description
DbMigrations(Datasource datasource)

Method Summary

Modifier and Type	Method	Description
DbMigrations	add(int version, DbMigration migration)	Registers a migration with an explicit version.
int	baseline(int version)	Records a version in the configured state without executing any migration.
int	currentVersion()	Retrieves the current version from the configured state.
int	migrate()	Migrates to the highest registered version, tracking the current version in the configured state.
int	migrate(int toVersion)	Migrates to a target version, tracking the current version in the configured state.
int	migrateFrom(int currentVersion)	Migrates from a provided current version to the highest registered version, without touching any state.
int	migrateFrom(int currentVersion, int toVersion)	Migrates from a provided current version to a target version, without touching any state.
List<Integer>	pending()	Retrieves the registered versions that haven't been applied yet according to the configured state.
List<Integer>	pendingFrom(int currentVersion)	Retrieves the registered versions that are higher than a provided current version.
List<String>	preview()	Generates the SQL statements of the pending migrations according to the configured state, without executing anything.
List<String>	previewFrom(int currentVersion)	Generates the SQL statements that would migrate from a provided current version to the highest registered version, without executing anything.
List<String>	previewFrom(int currentVersion, int toVersion)	Generates the SQL statements that would migrate from a provided current version to a target version, without executing anything.
int	rollback()	Rolls back the last applied migration, tracking the current version in the configured state.
int	rollback(int toVersion)	Rolls back to a target version, tracking the current version in the configured state.
int	rollbackFrom(int currentVersion)	Rolls back the migration that a provided current version corresponds to, without touching any state.
int	rollbackFrom(int currentVersion, int toVersion)	Rolls back from a provided current version to a target version, without touching any state.
DbMigrations	state(ResourceFinder finder, ResourceWriter writer, String resourceName)	Provides a separate state reader and writer with an explicit resource name.
<T extends ResourceFinder & ResourceWriter> DbMigrations	state(T resources)	Provides the state storage with the default resource name.
<T extends ResourceFinder & ResourceWriter> DbMigrations	state(T resources, String resourceName)	Provides the state storage with an explicit resource name.
List<Integer>	versions()	Retrieves the registered migration versions in order.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DbMigrations

public DbMigrations(Datasource datasource)

Method Details

add

public DbMigrations add(int version,
 DbMigration migration)

Registers a migration with an explicit version.

Versions have to be positive and strictly increasing in registration order, since the registered list is the complete migration history of your application.

Parameters:

version - the version this migration brings the schema to

migration - the migration to register

Returns:

this instance

Since:

1.10

See Also:

• versions()

state

public <T extends ResourceFinder & ResourceWriter>
DbMigrations state(T resources)

Provides the state storage with the default resource name.

The same instance is used to read and to write the version, while the resource name is taken from RifeConfig.migrations().

Type Parameters:

T - the type of the combined resource finder and writer

Parameters:

resources - the resource store for the migration state

Returns:

this instance

Since:

1.10

See Also:

• state(ResourceFinder, ResourceWriter, String)

state

public <T extends ResourceFinder & ResourceWriter>
DbMigrations state(T resources,
 String resourceName)

Provides the state storage with an explicit resource name.

The same instance is used to read and to write the version, which is stored under the resource name that you provide instead of the one that RifeConfig.migrations() configures.

Type Parameters:

T - the type of the combined resource finder and writer

Parameters:

resources - the resource store for the migration state

resourceName - the name of the resource that holds the version

Returns:

this instance

Since:

1.10

See Also:

• state(ResourceFinder, ResourceWriter, String)

state

public DbMigrations state(ResourceFinder finder,
 ResourceWriter writer,
 String resourceName)

Provides a separate state reader and writer with an explicit resource name.

The content of the state resource is trusted as-is, which means that editing it by hand is equivalent to calling baseline(int).

Parameters:

finder - the finder that reads the migration state

writer - the writer that stores the migration state

resourceName - the name of the resource that holds the version

Returns:

this instance

Since:

1.10

See Also:

• baseline(int)
• currentVersion()

versions

public List<Integer> versions()

Retrieves the registered migration versions in order.

This method will return every version that has been registered, whether it has already been applied to the schema or not.

Returns:

the registered versions

Since:

1.10

See Also:

• add(int, DbMigration)
• pending()
• pendingFrom(int)

pendingFrom

public List<Integer> pendingFrom(int currentVersion)

Retrieves the registered versions that are higher than a provided current version.

These are the migrations that migrateFrom(int) will execute for that same current version, no state is consulted since you provide the version yourself.

Parameters:

currentVersion - the version to compare against

Returns:

the pending versions

Since:

1.10

See Also:

• pending()
• migrateFrom(int)

migrateFrom

public int migrateFrom(int currentVersion)

Migrates from a provided current version to the highest registered version, without touching any state.

Since nothing is stored, the returned version is the only record of what has been applied and it's up to you to keep track of it.

This method will never move the schema backwards, so that a current version that already sits above every registered migration simply doesn't have anything to apply.

Parameters:

currentVersion - the version the schema is currently at

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• migrateFrom(int, int)
• migrate()

migrateFrom

public int migrateFrom(int currentVersion,
 int toVersion)

Migrates from a provided current version to a target version, without touching any state.

Only the migrations that sit above the current version and at or below the target version are executed. When you want to move the schema backwards, you have to use one of the rollback methods instead.

Parameters:

currentVersion - the version the schema is currently at

toVersion - the version to migrate to

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• migrateFrom(int)
• rollbackFrom(int, int)

rollbackFrom

public int rollbackFrom(int currentVersion)

Rolls back the migration that a provided current version corresponds to, without touching any state.

Only that single migration is reversed, which brings the schema back to the registered version that sits just below it. The migration has to extend ReversibleDbMigration, otherwise an IrreversibleMigrationException is raised.

Parameters:

currentVersion - the version the schema is currently at

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• rollbackFrom(int, int)
• rollback()

rollbackFrom

public int rollbackFrom(int currentVersion,
 int toVersion)

Rolls back from a provided current version to a target version, without touching any state.

The migrations are reversed in descending order and each of them has to extend ReversibleDbMigration, otherwise an IrreversibleMigrationException is raised.

Parameters:

currentVersion - the version the schema is currently at

toVersion - the version to roll back to, 0 or a registered version

Returns:

the version the schema is at afterwards, which is the provided current version when no migration had to be reversed

Since:

1.10

See Also:

• rollbackFrom(int)
• migrateFrom(int, int)

baseline

public int baseline(int version)

Records a version in the configured state without executing any migration.

This makes it possible to adopt an existing database into the migration sequence, since the schema is declared to already be at the provided version so that only the later migrations will be applied by migrate().

Parameters:

version - the version the existing schema corresponds to, 0 or a registered migration version

Returns:

the recorded version

Since:

1.10

See Also:

• currentVersion()
• migrate()

preview

public List<String> preview()

Generates the SQL statements of the pending migrations according to the configured state, without executing anything.

This makes it possible to review what will happen to the schema before you commit to it.

Returns:

the SQL statements that migrate() would execute

Since:

1.10

See Also:

• previewFrom(int)
• previewFrom(int, int)

previewFrom

public List<String> previewFrom(int currentVersion)

Generates the SQL statements that would migrate from a provided current version to the highest registered version, without executing anything.

No state is consulted at all, since you provide the current version yourself. This method mirrors migrateFrom(int), so that a current version above every registered migration produces no statements instead of an error.

Parameters:

currentVersion - the version the schema is currently at

Returns:

the SQL statements that would be executed

Since:

1.10

See Also:

• preview()
• previewFrom(int, int)

previewFrom

public List<String> previewFrom(int currentVersion,
 int toVersion)

Generates the SQL statements that would migrate from a provided current version to a target version, without executing anything.

Every migration starts with a SQL comment that identifies it, while action steps merely show up as a placeholder comment since their Java logic can't be previewed.

Parameters:

currentVersion - the version the schema is currently at

toVersion - the version to migrate to

Returns:

the SQL statements that would be executed

Throws:

IllegalArgumentException - when the target version sits below the current version, just like migrateFrom(int, int) refuses to move backwards

Since:

1.10

See Also:

• preview()
• previewFrom(int)

currentVersion

public int currentVersion()

Retrieves the current version from the configured state.

The content of the state resource is read on every call, since no version is ever cached by this instance.

Returns:

the current version; or

0 if no migration was applied yet

Since:

1.10

See Also:

• baseline(int)
• state(ResourceFinder, ResourceWriter, String)

pending

public List<Integer> pending()

Retrieves the registered versions that haven't been applied yet according to the configured state.

These are the migrations that migrate() will execute.

Returns:

the pending versions

Since:

1.10

See Also:

• pendingFrom(int)
• versions()

migrate

public int migrate()

Migrates to the highest registered version, tracking the current version in the configured state.

This is the method that you'll typically call to bring the schema up to date with everything that has been registered. Each migration is executed together with its state update inside a single transaction.

This method will never move the schema backwards, so that a stored version that already sits above every registered migration simply doesn't have anything to apply.

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• migrate(int)
• preview()

migrate

public int migrate(int toVersion)

Migrates to a target version, tracking the current version in the configured state.

Only the migrations that sit above the stored version and at or below the target version are executed. When you want to move the schema backwards, you have to use rollback(int) instead.

Parameters:

toVersion - the version to migrate to

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• migrate()
• rollback(int)

rollback

public int rollback()

Rolls back the last applied migration, tracking the current version in the configured state.

Only that single migration is reversed, which brings the schema back to the registered version that sits just below it. The migration has to extend ReversibleDbMigration, otherwise an IrreversibleMigrationException is raised.

Returns:

the version the schema is at afterwards

Since:

1.10

See Also:

• rollback(int)
• migrate()

rollback

public int rollback(int toVersion)

Rolls back to a target version, tracking the current version in the configured state.

The migrations are reversed in descending order and each of them has to extend ReversibleDbMigration, otherwise an IrreversibleMigrationException is raised. Every reversal is executed together with its state update inside a single transaction.

Parameters:

toVersion - the version to roll back to, 0 or a registered version

Returns:

the version the schema is at afterwards, which is the stored version when no migration had to be reversed

Since:

1.10

See Also:

• rollback()
• migrate(int)