Client and backend. This class is shared: the same code is compiled into your app and into your server, so everything on this page works in both.

public final class Migrator

Object
Migrator

Runs one MigrationSet against one database.

Obtain one from the runtime’s Migrations class: com.codename1.db.Migrations.of(database) in an application, com.codename1.backend.Migrations.of(dataSource) on a server. The commands and settings are Flyway’s, and the history table is Flyway’s, so the same scripts and the same history work under either.

MigrateResult result = Migrations.of(database).baselineOnMigrate(true).migrate();

A migrator holds no connection state between calls and is not thread safe.

Methods

`public` `MigrationSet getSet()`	The set this migrator runs.
`public` `Migrator table(String table)`	Uses a history table other than the set’s own.
`public` `Migrator baselineOnMigrate(boolean value)`	Adopts a database that already has tables and no history, by recording a baseline before migrating instead of refusing.
`public` `Migrator baselineVersion(String version)`	The version an adopted database is taken to be at; migrations at or below it never run.
`public` `Migrator baselineDescription(String description)`	The description written on the baseline row.
`public` `Migrator validateOnMigrate(boolean value)`	Whether `migrate()` first checks that every applied migration is still present and unchanged.
`public` `Migrator outOfOrder(boolean value)`	Whether a migration older than the newest applied one is applied instead of refused.
`public` `Migrator cleanDisabled(boolean value)`	Whether `clean()` is refused.
`public` `Migrator target(String version)`	The highest version to apply.
`public` `Migrator ignoreFutureMigrations(boolean value)`	Whether a database migrated by a newer build is tolerated.
`public` `Migrator installedBy(String name)`	The name recorded in the history as having applied each migration.
`public` `Migrator lockRetryCount(int attempts)`	How long to wait for another process that is migrating the same database, in roughly one-second attempts.
`public` `MigrateResult migrate() throws IOException`	Applies every migration that has not run yet, in version order, then every repeatable migration whose script changed.
`public` `MigrationInfo[] info() throws IOException`	Reports every migration, applied or pending, without changing anything.
`public void validate() throwsIOException`	Throws unless the database is exactly at this build’s migrations: nothing pending, nothing edited, nothing missing.
`public void baseline() throwsIOException`	Marks an existing database as already being at the baseline version.
`public void repair() throwsIOException`	Deletes the rows of failed migrations and rewrites recorded checksums to match the scripts in this build.
`public void clean() throwsIOException`	Drops every table and view in the database, the history included.

Inherited methods

From Object

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

Method details

getSet

public MigrationSet getSet()

The set this migrator runs.

Returns

the migration set

table

public Migrator table(String table)

Uses a history table other than the set’s own.

Parameters

table String: a plain identifier of at most 53 characters

Returns

this migrator

baselineOnMigrate

public Migrator baselineOnMigrate(boolean value)

Adopts a database that already has tables and no history, by recording a baseline before migrating instead of refusing. Off by default: silently adopting a schema of unknown shape is how a migration runs against the wrong database.

Parameters

value boolean: true to baseline on the first migrate

Returns

this migrator

baselineVersion

public Migrator baselineVersion(String version)

The version an adopted database is taken to be at; migrations at or below it never run.

Parameters

version String: the baseline version, 1 by default

Returns

this migrator

baselineDescription

public Migrator baselineDescription(String description)

The description written on the baseline row.

Parameters

description String: the description

Returns

this migrator

validateOnMigrate

public Migrator validateOnMigrate(boolean value)

Whether migrate() first checks that every applied migration is still present and unchanged. On by default.

Parameters

value boolean: false to skip the check

Returns

this migrator

outOfOrder

public Migrator outOfOrder(boolean value)

Whether a migration older than the newest applied one is applied instead of refused.

Parameters

value boolean: true to allow it

Returns

this migrator

cleanDisabled

public Migrator cleanDisabled(boolean value)

Whether clean() is refused. On by default.

Parameters

value boolean: false to allow clean

Returns

this migrator

target

public Migrator target(String version)

The highest version to apply.

Parameters

version String: the version, or null for the newest

Returns

this migrator

ignoreFutureMigrations

public Migrator ignoreFutureMigrations(boolean value)

Whether a database migrated by a newer build is tolerated. A server tolerates it, because a rolling deployment runs old and new builds against one database. An application refuses it by default, because the build on the device cannot know what a newer one did to its tables.

Parameters

value boolean: true to continue with a warning, false to throw

Returns

this migrator

installedBy

public Migrator installedBy(String name)

The name recorded in the history as having applied each migration.

Parameters

name String: the name, or null for the runtime’s default

Returns

this migrator

lockRetryCount

public Migrator lockRetryCount(int attempts)

How long to wait for another process that is migrating the same database, in roughly one-second attempts.

Parameters

attempts int: the number of attempts, 50 by default

Returns

this migrator

migrate

public MigrateResult migrate()
throws IOException

Applies every migration that has not run yet, in version order, then every repeatable migration whose script changed.

Returns

what ran

Throws

MigrationException: if the history does not match, a script fails, or the database is not in a state to migrate; the code says which
IOException: if the database fails outside a migration

info

public MigrationInfo[] info()
throws IOException

Reports every migration, applied or pending, without changing anything.

Returns

applied migrations in the order they ran, then the ones that have not

Throws

IOException: if the history cannot be read

validate

public void validate()
throws IOException

Throws unless the database is exactly at this build’s migrations: nothing pending, nothing edited, nothing missing. A repeatable migration that has not run, or whose script changed since it last ran, is pending.

Throws

MigrationException: on any difference
IOException: if the history cannot be read

baseline

public void baseline()
throws IOException

Marks an existing database as already being at the baseline version.

Throws

IOException: if the history already records migrations or cannot be written

repair

public void repair()
throws IOException

Deletes the rows of failed migrations and rewrites recorded checksums to match the scripts in this build. Run it after cleaning up what a failed migration left behind, or after deliberately editing an applied script.

Throws

IOException: if the history cannot be written

clean

public void clean()
throws IOException

Drops every table and view in the database, the history included.

Throws

MigrationException: unless clean was enabled with cleanDisabled(boolean)
IOException: if the database refuses