Introduction

DB Migration introduction

Introduction to DB migration

Repeatable migrations

Use of @View, extra-ddl.xml and repeatable migrations

Overview

DB Migration is a feature for generation of DDL from the entity bean model that supports determining the diff from the prior version of the model and generating appropriate DDL changes based on the model difference.

You are expected to run the diff DDL using Ebean's own migration runner. Alternatively the migrations can be run via FlywayDb or LiquiBase.

DB migration has 2 output files:

  • Migration model XML - This has the logical diff of the model as an apply or pendingDrops change set
  • Apply SQL - This is the DDL script of the apply changes

How to generate a Migration

In src/test/java add code to generate migrations.

package main;

import io.ebean.annotation.Platform;
import io.ebean.dbmigration.DbMigration;
import java.io.IOException;

public class GenerateDbMigration {

  /**
   * Generate the next "DB schema DIFF" migration.
   */
  public static void main(String[] args) throws IOException {


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

    dbMigration.generateMigration();
  }
}

To generate a migration we run this main method. We run this manually when we have completed some work and consider it ready to be released. Running the generation starts the EbeanServer in offline mode, performs a DIFF of the model and generates the migration script.

How to run a Migration

To run the migration using the built in migration runner, set ebean.migration.run to true.

In application.yml
## run migrations when the EbeanServer starts
ebean:
  migration:
    run: true

With ebean.migration.run=true then when the EbeanServer starts it will look at the migrations and run any that need to be run. The migration runner will by default create a table called db_migration that holds the meta data about the migrations that have been run and inserts into this table when migrations are successfully executed.