Flyway能否在配置项目外运行Java类迁移脚本？为何脚本被忽略？

Great question—while checksum mismatches can cause Flyway headaches, they usually scream about it with an error message instead of silently ignoring a script. Let’s walk through the most likely issues here, starting with the easiest checks first:

1. Double-Check Your Java Migration Class Rules #

Flyway is picky about Java migration classes—miss one rule, and it’ll act like the file doesn’t exist:

• Must implement/extend the right class: Your Java class needs to extend org.flywaydb.core.api.migration.BaseJavaMigration (or implement JavaMigration directly). No exceptions here.
• Naming pattern is non-negotiable: The class name has to follow V<version>__<description>.java—note that double underscore between the version and description. Your example uses V3__SampleJava_script.java, which looks right, but triple-check you didn’t use a single underscore by accident.
• Public + no-arg constructor: The class has to be public, and it needs a default no-argument constructor (even if it’s empty—Flyway needs to instantiate it).

Here’s a quick valid example to compare against:

package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import java.sql.PreparedStatement;

public class V3__SampleJava_script extends BaseJavaMigration {
    @Override
    public void migrate(Context context) throws Exception {
        // Your complex logic goes here
        try (PreparedStatement stmt = context.getConnection().prepareStatement("INSERT INTO sample_table (data) VALUES (?)")) {
            stmt.setString(1, "From Java migration!");
            stmt.execute();
        }
    }
}

2. Make Sure Your Compiled .class Files Are On the Classpath #

This is a super common gotcha. When you run your Flyway jar, the compiled V3__SampleJava_script.class file needs to be on the JVM’s classpath. Since your scripts are in a separate project (C:/database-migration-scripts), you have two main options:

• Package the migration classes into a jar: Build your script project into a jar, then include it alongside your Flyway jar when running:

  # Windows
  java -cp "W:/someLocationOutsideProject/flyway-database-migration.jar;C:/database-migration-scripts/target/database-migration-scripts.jar" com.your.main.ClassName
  
  # Linux/macOS
  java -cp "W:/someLocationOutsideProject/flyway-database-migration.jar:C:/database-migration-scripts/target/database-migration-scripts.jar" com.your.main.ClassName
  

• Add the target/classes directory directly: If you don’t want to build a jar, you can point the classpath to the compiled classes folder:

  java -cp "W:/someLocationOutsideProject/flyway-database-migration.jar;C:/database-migration-scripts/target/classes" com.your.main.ClassName
  

Important note: Flyway only scans SQL scripts from the directory you pass via locations—Java migrations can’t be loaded from that directory alone; they have to be on the classpath.

3. Check Your Flyway Configuration #

A few config settings might be hiding your migration:

• flyway.locations: Make sure you haven’t restricted locations to only filesystem:path—Java migrations live in classpath:db/migration by default, so your config should include that (or just let Flyway use its default locations).
• flyway.baselineVersion: If you set a baseline version higher than V3, Flyway will skip all migrations below that version (including V3). Double-check this isn’t set accidentally.
• flyway.validateOnMigrate: While this won’t cause ignoring, if there’s a checksum mismatch, Flyway will fail here instead of running the migration—but you’d get an error message for that, not silence.

4. Rule Out Checksum Issues (Just to Be Thorough) #

Like I said earlier, checksum mismatches usually throw an explicit error (something like Checksum mismatch for migration version 3), but you can confirm by:

• Looking at the flyway_schema_history table in your database. If there’s already an entry for V3 with a different checksum, that’s the problem.
• If you need to debug, temporarily set flyway.validateOnMigrate=false when running Flyway—but only do this to test, not as a permanent fix.

5. Ensure Flyway Version Compatibility #

Make sure the Flyway version you used to compile your Java migration (in your script project’s pom.xml) matches the version embedded in your flyway-database-migration.jar. Mismatched versions can lead to class loading errors that make Flyway ignore the migration silently.

Start with the class naming and classpath checks—those are the two most likely culprits. Once you nail those, your Java migration should show up in Flyway’s migration list.

内容的提问来源于stack exchange，提问作者Vinni