Class Migrations

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

Versioned schema migrations for the application's SQLite database.

Put scripts named V<version>__<description>.sql in the project's src/main/db/migration directory. The build compiles them into the application, and one call brings whatever database the device holds up to the version this build expects:

Database db = Display.getInstance().openOrCreate("notes.db");
Migrations.migrate(db);

Each script runs once, in version order, inside a transaction, and is recorded in the flyway_schema_history table with a checksum. A script that has run is never edited: a change to the schema is a new script with a higher version.

Call this on the thread that owns the database, before anything else uses it, and not on the event dispatch thread if the scripts are large. A database that a newer build of the application already migrated is refused with MigrationException.FUTURE_SCHEMA before anything is changed, so an older build installed over newer data fails loudly instead of misreading its tables.

The same engine, scripts and history table are used by the Codename One backend.

  • 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.
      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 migrate(Database) has something to run

    • of

      public static Migrator of(Database db)
      A migrator for the application's own set.
      Parameters:
      db - the database, owned by the caller and used from the calling thread
      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.
      Parameters:
      db - the database, owned by the caller and used from the calling thread
      set - the migrations to run
      Returns:
      a migrator to configure and run

    • migrate

      public static MigrateResult migrate(Database db) throws IOException
      Applies every pending migration of every registered set: library sets first, the application's own last. Does nothing when no set is registered.
      Parameters:
      db - the database, owned by the caller and used from the calling thread
      Returns:
      what ran; the versions are those of the application's own set
      Throws:
      MigrationException - if a migration fails or the database does not match this build
      IOException - if the database fails