NativeImageResourceProvider does not find Flyway migration scripts in subdirectories

[sondemar]

Follows from #31999, which introduced NativeImageResourceProvider as the solution for Flyway classpath scanning in native images. This reports a gap in that implementation: subdirectory migration locations are not supported.

Problem

NativeImageResourceProvider uses a single-level glob when scanning the classpath migration locations at runtime in a native image:

// NativeImageResourceProvider.java
private Resource[] getResources(PathMatchingResourcePatternResolver resolver, Location location, Resource root) {
    try {
        return resolver.getResources(root.getURI() + "/*");
    }
    ...
}

The /* pattern matches only files directly under the root location. Migration script placed in subdirectories (a common convention in larger projects, e.g. db/migration/1.0.0/V1__init.sql, db/migration/2.0.0/V2__add_column.sql) are silently skipped, causing Flyway to find no migrations and fail or produce an empty schema.

Note: the resources are correctly bundled in the native image when resource hints register db/migration/**. The failure is purely in runtime discovery.

Expected behaviour

All migration scripts under a configured location are found regardless of nesting depth, consistent with the behaviour of Flyway on a regular JVM.

Actual behaviour

Only scripts directly under the location root (e.g. db/migration/V1__init.sql) are found. Scripts in subdirectories (e.g. db/migration/1.0.0/V1__init.sql) are not discovered and Flyway does not run them.

Proposed fix

Change /* to /**/* in getResources():

  // before
  return resolver.getResources(root.getURI() + "/*");

  // after
  return resolver.getResources(root.getURI() + "/**/*");

This also requires fixing asClassPathResource to keep the full subdirectory path. With /*, resources are always one level deep, so location.getRootPath() + "/" + filename is correct. When changed to /**/*, subdirectory resources appear and that construction flattens db/migration/1.0.0/V1__init.sql incorrectly to db/migration/V1__init.sql:

  // before — correct only for flat locations, breaks with /**/*
  String fileNameWithAbsolutePath = location.getRootPath() + "/" + locatedResource.resource().getFilename();

  // after — uses the full classpath-relative path from the resolver result
  private String resolveClasspathPath(Resource resource, Location location) {
      if (resource instanceof ClassPathResource cpr) {
          return cpr.getPath(); // e.g. "db/migration/1.0.0/V1__init.sql"
      }
      return location.getRootPath() + "/" + resource.getFilename(); // fallback
  }

Reproduce

  PathMatchingResourcePatternResolver resolver = new PathMatchingResourcePatternResolver();
  Resource root = resolver.getResource("classpath:db/migration");

  // current — misses subdirectory scripts
  Resource[] shallow = resolver.getResources(root.getURI() + "/*");

  // expected
  Resource[] recursive = resolver.getResources(root.getURI() + "/**/*");

With db/migration/V1__flat.sql and db/migration/1.0.0/V2__subdir.sql on the classpath, shallow contains only V1__flat.sql but recursive contains both.

Spring Boot version: 4.0.0

[ThomasVitale]

I recently bumped into issues also with first-level migrations, but it turned out to be a false positive: #49602 perhaps you have some inputs on how to document the native support for Flyway migration scripts, including the limitation described in here until it's fixed.

[wilkinsona]

Note: the resources are correctly bundled in the native image when resource hints register db/migration/**. The failure is purely in runtime discovery.

@sondemar, are you talking about your own custom resource hints here? As far as I can tell, Boot's own hints and its resource provider are aligned:

spring-boot/module/spring-boot-flyway/src/main/java/org/springframework/boot/flyway/autoconfigure/FlywayAutoConfiguration.java

Line 483 in d57a81c

hints.resources().registerPattern("db/migration/*");

[bclozel]

The Flyway official documentation discovers scripts by looking into folders, and non-hidden sub-directories:

This scanning is recursive. All migrations in non-hidden directories below the specified ones are also picked up.

So I think we need to update our resource hint to hints.resources().registerPattern("db/migration/**"); to effectively register a globstar per GraalVM metadata format.

[sondemar]

Note: the resources are correctly bundled in the native image when resource hints register db/migration/**. The failure is purely in runtime discovery.

@sondemar, are you talking about your own custom resource hints here? As far as I can tell, Boot's own hints and its resource provider are aligned:

spring-boot/module/spring-boot-flyway/src/main/java/org/springframework/boot/flyway/autoconfigure/FlywayAutoConfiguration.java

Line 483 in d57a81c

hints.resources().registerPattern("db/migration/*");

@wilkinsona
Yes, db/migration/** bundling requires a custom RuntimeHintsRegistrar. Spring Boot's FlywayAutoConfigurationRuntimeHints only registers db/migration/*, so subdirectory scripts are not bundled at all. The issue has two separate gaps that must both be addressed for subdirectory migrations to work in native image:

1. While building FlywayAutoConfigurationRuntimeHints registers db/migration/* which does not include scripts in subdirectories such as db/migration/1.0.0/V1__init.sql. Adding db/migration/** would fix this.
2. While runtime discovery, even when subdirectory scripts are correctly bundled (via custom hints), NativeImageResourceProvider scans single level, which only finds flat migrations. In a native image root.getURI() returns a resource: URI, and PathMatchingResourcePatternResolver does
   not enumerate subdirectories against that scheme. Changing the scan to use location.getDescriptor() + "/**/*" (i.e. classpath:db/migration/**/*) should resolve the discovery issue.

So your observation is correct, the hints and provider are aligned today, but both need updating to support the subdirectory pattern.