Custom MigrationLoader

Sometimes, you want or need to organize your migration scripts differently than the default way.
Since version 3.3.2, you can let Migrations use a custom MigrationLoader to customize how migration scripts are loaded.


To let Migrations use a custom MigrationLoader, you need to...

  • Create a class that implements MigrationLoader.
  • Create a class that implements FileMigrationLoaderFactory.
  • Create a text file that contains the fully qualified name of the FileMigrationLoaderFactory implementation class.
  • Create a JAR archive that contains the above files.
  • Put the JAR archive in $MIGRATIONS_HOME/lib directory.


Here is the declaration of MigrationLoader interface.
Instead of implementing the interface from scratch, you can create a subclass of the default FileMigrationLoader if it is easier.

package org.apache.ibatis.migration;

import java.util.List;

public interface MigrationLoader {
   * @return A list of migrations (bootstrap should NOT be included).
  List<Change> getMigrations();

   * @param change identifies the migration to read.
   * @param undo whether the caller requests UNDO SQL script or not.
   * @return A {@link Reader} of the specified SQL script.
  Reader getScriptReader(Change change, boolean undo);

   * @return A {@link Reader} of the bootstrap SQL script.
  Reader getBootstrapReader();

   * @return A {@link Reader} of the onabort SQL script.
  Reader getOnAbortReader();


FileMigrationLoaderFactory interface has only one method. Your implementation should return the custom MigrationLoader that you wrote.

package org.apache.ibatis.migration;

public interface FileMigrationLoaderFactory {
  MigrationLoader create(SelectedPaths paths, Environment environment);

Mapping file for Java SPI

This text file is used by Java Service Provider Interface (SPI), so it must contain the fully qualified name of your custom FileMigrationLoaderFactory class.
In the JAR archive, its file path must be /META-INF/services/org.apache.ibatis.migration.FileMigrationLoaderFactory.