Package io.ebean.dbmigration

Interface DbMigration

All Known Implementing Classes:
DefaultDbMigration
public interface DbMigration
Generates DDL migration scripts based on changes to the current model.

Typically this is run as a main method in src/test once a developer is happy with the next set of changes to the model.

Example: Run for a single specific platform



    DbMigration migration = DbMigration.create();

    migration.setPlatform(Platform.POSTGRES);

    // optionally specify the version and name
    migration.setName("add indexes to customer");

    migration.generateMigration();

Drop column migrations are effectively breaking changes and should be held back and run in a later migration after the columns deleted are no longer being used by the application. These changes are called "pending drops" and we must explicitly specify to include these in a generated migration.

Use setGeneratePendingDrop() to specify a prior migration that has drop column changes that we want to generate a migration for.

Example: Generate for pending drops



    DbMigration migration = DbMigration.create();

    migration.setPlatform(Platform.POSTGRES);

    // set the migration version that has pending drops
    migration.setGeneratePendingDrop("1.3");

    // generates the migration with drop column changes
    migration.generateMigration();

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addDatabasePlatform(io.ebean.config.dbplatform.DatabasePlatform databasePlatform, String prefix)
    Add a databasePlatform to write the migration DDL.
    void
    addPlatform(io.ebean.annotation.Platform platform)
    Add a platform to write the migration DDL.
    void
    addPlatform(io.ebean.annotation.Platform platform, String prefix)
    Add a platform to write with a given prefix.
    static DbMigration
    create()
    Create a DbMigration implementation to use.
    String
    generateInitMigration()
    Generate an "init" migration which has all changes.
    String
    generateMigration()
    Generate the next migration sql script and associated model xml.
    List<String>
    getPendingDrops()
    Return the list of versions that contain pending drops.
    File
    migrationDirectory()
    Return the main migration directory.
    void
    setAddForeignKeySkipCheck(boolean addForeignKeySkipCheck)
    Set to true if ALTER TABLE ADD FOREIGN KEY should be generated with an option to skip validation.
    void
    setApplyPrefix(String applyPrefix)
    Set the prefix for the version.
    void
    setGeneratePendingDrop(String generatePendingDrop)
    Generate a migration for the version specified that contains pending drops.
    void
    setHeader(String header)
    Set the header that is included in the generated DDL script.
    void
    setIncludeBuiltInPartitioning(boolean includeBuiltInPartitioning)
    Set this to false to exclude the builtin support for table partitioning (with @DbPartition).
    void
    setIncludeGeneratedFileComment(boolean includeGeneratedFileComment)
    Set to true to include a generated header comment in the DDL script.
    void
    setIncludeIndex(boolean generateIndexFile)
    Set to include generation of the index migration file.
    void
    setLockTimeout(int seconds)
    Set the lock timeout to be included with the DDL generation.
    void
    setLogToSystemOut(boolean logToSystemOut)
    Set logging to System out (defaults to true).
    void
    setMigrationPath(String migrationPath)
    Set the path where migrations are generated to (which defaults to "dbmigration").
    void
    setName(String name)
    Set the name of the migration to be generated.
    void
    setPathToResources(String pathToResources)
    Set the path from the current working directory to the application resources.
    void
    setPlatform(io.ebean.annotation.Platform platform)
    Set the specific platform to generate DDL for.
    void
    setPlatform(io.ebean.config.dbplatform.DatabasePlatform databasePlatform)
    Set the specific platform to generate DDL for.
    void
    setServer(io.ebean.Database database)
    Set the server to use to determine the current model.
    void
    setServerConfig(io.ebean.config.DatabaseConfig config)
    Set the DatabaseConfig to use.
    void
    setStrictMode(boolean strictMode)
    Set to false in order to turn off strict mode.
    void
    setVersion(String version)
    Set the version of the migration to be generated.

  • Method Details

    • create

      static DbMigration create()
      Create a DbMigration implementation to use.

    • setLogToSystemOut

      void setLogToSystemOut(boolean logToSystemOut)
      Set logging to System out (defaults to true).

    • setPathToResources

      void setPathToResources(String pathToResources)
      Set the path from the current working directory to the application resources.

      This defaults to maven style 'src/main/resources'.

    • setMigrationPath

      void setMigrationPath(String migrationPath)
      Set the path where migrations are generated to (which defaults to "dbmigration").

      Normally we only use this when we use Ebean to generate the database migrations and then use some other tool like FlywayDB to run the migrations.

      Example: with setMigrationPath("db/migration") ... the migrations are generated into src/resources/db/migration.

      Note that if Ebean migration runner is used we should not use this method but instead set the migrationPath via a property such that both the migration generator and migration runner both use the same path.

      Parameters:
      migrationPath - The path that migrations are generated into.

    • setServer

      void setServer(io.ebean.Database database)
      Set the server to use to determine the current model. Usually this is not called explicitly.

    • setServerConfig

      void setServerConfig(io.ebean.config.DatabaseConfig config)
      Set the DatabaseConfig to use. Usually this is not called explicitly.

    • setPlatform

      void setPlatform(io.ebean.annotation.Platform platform)
      Set the specific platform to generate DDL for.

      If not set this defaults to the platform of the default database.

    • setPlatform

      void setPlatform(io.ebean.config.dbplatform.DatabasePlatform databasePlatform)
      Set the specific platform to generate DDL for.

      If not set this defaults to the platform of the default database.

    • setStrictMode

      void setStrictMode(boolean strictMode)
      Set to false in order to turn off strict mode.

      Strict mode checks that a column changed to non-null on an existing table via DB migration has a default value specified. Set this to false if that isn't the case but it is known that all the existing rows have a value specified (there are no existing null values for the column).

    • setIncludeIndex

      void setIncludeIndex(boolean generateIndexFile)
      Set to include generation of the index migration file.

      When true this generates a idx_<platform>.migrations file. This can be used by the migration runner to improve performance of running migrations, especially when no migration changes have occurred.

    • setIncludeGeneratedFileComment

      void setIncludeGeneratedFileComment(boolean includeGeneratedFileComment)
      Set to true to include a generated header comment in the DDL script.

    • setIncludeBuiltInPartitioning

      void setIncludeBuiltInPartitioning(boolean includeBuiltInPartitioning)
      Set this to false to exclude the builtin support for table partitioning (with @DbPartition).

    • setHeader

      void setHeader(String header)
      Set the header that is included in the generated DDL script.

    • setApplyPrefix

      void setApplyPrefix(String applyPrefix)
      Set the prefix for the version. Set this to "V" for use with Flyway.

    • setVersion

      void setVersion(String version)
      Set the version of the migration to be generated.

    • setName

      void setName(String name)
      Set the name of the migration to be generated.

    • setGeneratePendingDrop

      void setGeneratePendingDrop(String generatePendingDrop)
      Generate a migration for the version specified that contains pending drops.
      Parameters:
      generatePendingDrop - The version of a prior migration that holds pending drops.

    • setAddForeignKeySkipCheck

      void setAddForeignKeySkipCheck(boolean addForeignKeySkipCheck)
      Set to true if ALTER TABLE ADD FOREIGN KEY should be generated with an option to skip validation.

      Currently this is only useful for Postgres DDL adding the NOT VALID option.

    • setLockTimeout

      void setLockTimeout(int seconds)
      Set the lock timeout to be included with the DDL generation.

      Currently this is only useful for Postgres migrations adding a set lock_timeout statement to the generated database migration.

    • addPlatform

      void addPlatform(io.ebean.annotation.Platform platform)
      Add a platform to write the migration DDL.

      Use this when you want to generate sql scripts for multiple database platforms from the migration (e.g. generate migration sql for MySql, Postgres and Oracle).

    • addPlatform

      void addPlatform(io.ebean.annotation.Platform platform, String prefix)
      Add a platform to write with a given prefix.

    • addDatabasePlatform

      void addDatabasePlatform(io.ebean.config.dbplatform.DatabasePlatform databasePlatform, String prefix)
      Add a databasePlatform to write the migration DDL.

      Use this when you want to add preconfigured database platforms.

    • getPendingDrops

      List<String> getPendingDrops()
      Return the list of versions that contain pending drops.

    • migrationDirectory

      File migrationDirectory()
      Return the main migration directory.

    • generateMigration

      String generateMigration() throws IOException
      Generate the next migration sql script and associated model xml.

      This does not run the migration or ddl scripts but just generates them.

      Example: Run for a single specific platform

      

   DbMigration migration = DbMigration.create();
   migration.setPlatform(Platform.POSTGRES);

   migration.generateMigration();

      Example: Generate for "pending drops" (drop column changes)

      

    DbMigration migration = DbMigration.create();

    migration.setPlatform(Platform.POSTGRES);

    // set the migration version that has pending drops
    migration.setGeneratePendingDrop("1.3");

    // generates the migration with drop column changes
    migration.generateMigration();

      Example: Run migration generating DDL for multiple platforms

      

   DbMigration migration = DbMigration.create();

   migration.setPathToResources("src/main/resources");

   migration.addPlatform(Platform.POSTGRES);
   migration.addPlatform(Platform.MYSQL);
   migration.addPlatform(Platform.ORACLE);

   migration.generateMigration();
      Returns:
      the version of the generated migration or null
      Throws:
      IOException

    • generateInitMigration

      String generateInitMigration() throws IOException
      Generate an "init" migration which has all changes.

      An "init" migration can only be executed and used on a database that has had no prior migrations run on it.

      Returns:
      the version of the generated migration
      Throws:
      IOException