Class Migrator

java.lang.Object
com.codename1.migration.Migrator
public final class Migrator extends Object

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.

  • 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 - 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 - 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 - the baseline version, 1 by default
      Returns:
      this migrator

    • baselineDescription

      public Migrator baselineDescription(String description)
      The description written on the baseline row.
      Parameters:
      description - 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 - 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 - true to allow it
      Returns:
      this migrator

    • cleanDisabled

      public Migrator cleanDisabled(boolean value)
      Whether clean() is refused. On by default.
      Parameters:
      value - false to allow clean
      Returns:
      this migrator

    • target

      public Migrator target(String version)
      The highest version to apply.
      Parameters:
      version - 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 - 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 - 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 - 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