Class Migrations

java.lang.Object
com.codename1.backend.Migrations
public final class Migrations extends Object

Versioned schema migrations for the server's database.

Put scripts named V<version>__<description>.sql in src/main/resources/db/migration. The build compiles them into the server, and the server applies whatever has not run yet before it opens the entity manager or accepts a request. A script for one engine only goes in a sqlite, postgresql or mysql subdirectory.

Each script runs once, in version order, and is recorded with a checksum in the flyway_schema_history table -- the table, the file naming and the commands are Flyway's, so a schema already managed by Flyway carries straight over. Several server processes starting at once against one database take a lock, so each migration still runs exactly once.

The settings mirror Spring Boot's spring.flyway.* under cn1.flyway.*; see Config. This class is for the cases start-up does not cover: running a migration by hand, reading the state of the schema, or migrating a database the server was not configured with.

MigrationInfo[] state = Migrations.of(pool).info();
Migrations.of(pool).repair();

On MySQL and MariaDB a schema change commits as it runs and cannot be rolled back. A script that fails there is recorded as failed and every later start refuses to migrate until Migrator.repair() has been called.

  • Method Details

    • register

      public static void register(MigrationSet set)
      Registers a migration set. The build registers the application's own; a library that keeps tables of its own registers one under its own name, and it then runs before the application's.
      Parameters:
      set - the set to register, replacing one of the same name

    • isRegistered

      public static boolean isRegistered()
      Whether any migration set is registered.
      Returns:
      true when the server has migrations to run at start-up

    • of

      public static Migrator of(DataSource pool)
      A migrator for the application's own set.
      Parameters:
      pool - the database
      Returns:
      a migrator to configure and run
      Throws:
      IllegalStateException - if the build found no migrations and none was registered

    • of

      public static Migrator of(DataSource pool, MigrationSet set)
      A migrator for a specific set.
      Parameters:
      pool - the database
      set - the migrations to run
      Returns:
      a migrator to configure and run

    • of

      public static Migrator of(Database db)
      A migrator for the application's own set over one connection the caller owns.
      Parameters:
      db - the connection
      Returns:
      a migrator to configure and run
      Throws:
      IllegalStateException - if the build found no migrations and none was registered

    • of

      public static Migrator of(Database db, MigrationSet set)
      A migrator for a specific set over one connection the caller owns.
      Parameters:
      db - the connection
      set - the migrations to run
      Returns:
      a migrator to configure and run

    • configure

      public static Migrator configure(Migrator migrator, Config config) throws IOException
      Applies the settings a deployment configured to a migrator. cn1.flyway.table names the application's own history table only: a library's set keeps its own.
      Parameters:
      migrator - the migrator to configure
      config - the configuration to read cn1.flyway.* from
      Returns:
      the same migrator
      Throws:
      IOException - if a setting cannot be read

    • migrate

      public static int migrate(DataSource pool, Config config) throws IOException
      Applies every pending migration of every registered set, as start-up does: library sets first, the application's own last, each configured from cn1.flyway.*.
      Parameters:
      pool - the database
      config - the configuration
      Returns:
      the number of migrations that ran
      Throws:
      MigrationException - if a migration fails or the schema does not match this build
      IOException - if the database fails