GH-1440 - Revamp application-module-specific Flyway migration to fully isolate modules.

We now set up completely independent migrations per module.

Author: odrotbohm

spring-modulith-runtime/src/main/java/org/springframework/modulith/runtime/flyway/SpringModulithFlywayMigrationStrategy.java

@@ -21,6 +21,8 @@
 import org.flywaydb.core.Flyway;
 import org.flywaydb.core.api.Location;
 import org.flywaydb.core.api.configuration.Configuration;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.boot.flyway.autoconfigure.FlywayMigrationStrategy;
 import org.springframework.modulith.core.ApplicationModuleIdentifier;
 import org.springframework.modulith.core.ApplicationModuleIdentifiers;
@@ -36,6 +38,9 @@
  */
 public class SpringModulithFlywayMigrationStrategy implements FlywayMigrationStrategy {
 
+	private static final ApplicationModuleIdentifier ROOT = ApplicationModuleIdentifier.of("__root");
+	private static final Logger LOGGER = LoggerFactory.getLogger(SpringModulithFlywayMigrationStrategy.class);
+
 	private final ApplicationModuleIdentifiers identifiers;
 
 	/**
@@ -66,45 +71,52 @@ static class SpringModulithFlywayCustomizer {
 
 		private final Flyway flyway;
 
-		/**
-		 * @param flyway
-		 */
 		SpringModulithFlywayCustomizer(Flyway flyway) {
 			this.flyway = flyway;
 		}
 
 		Stream<Flyway> augment(ApplicationModuleIdentifiers identifiers) {
 
 			var configuration = flyway.getConfiguration();
-			var original = Stream.of(flyway);
+			return Stream.concat(Stream.of(ROOT), identifiers.stream())
+					.peek(it -> LOGGER.debug("Executing Flyway migrations for application module {}.", it))
+					.map(it -> augmentWithApplicationModule(it, configuration));
+		}
 
-			if (Stream.of(configuration.getLocations()).map(Location::toString).anyMatch(it -> it.endsWith("*"))) {
-				return original;
-			}
+		private Flyway augmentWithApplicationModule(ApplicationModuleIdentifier identifier,
+				Configuration configuration) {
 
-			var augmented = identifiers.stream()
-					.map(it -> augmentWithApplicationModule(it, configuration))
-					.map(it -> withNewLocation(configuration, it));
+			var locations = Stream.of(configuration.getLocations())
+					.map(Location::toString)
+					.map(it -> customizeLocation(it, identifier))
+					.toList();
 
-			return Stream.concat(original, augmented);
+			return withNewLocation(configuration, locations, identifier);
 		}
 
-		private List<String> augmentWithApplicationModule(ApplicationModuleIdentifier identifier,
-				Configuration configuration) {
+		private static String customizeLocation(String location, ApplicationModuleIdentifier identifier) {
+
+			if (location.endsWith("*")) {
+				return location;
+			}
 
 			var asPath = identifier.toString().replace('.', '/');
 
-			return Stream.of(configuration.getLocations())
-					.map(Location::toString)
-					.map(it -> it.concat("/").concat(asPath))
-					.toList();
+			return location + "/" + asPath;
 		}
 
-		private static Flyway withNewLocation(Configuration configuration, List<String> locations) {
+		private static Flyway withNewLocation(Configuration configuration, List<String> locations,
+				ApplicationModuleIdentifier identifier) {
+
+			var table = configuration.getTable();
+			var customizedTable = identifier.equals(ROOT) ? table : table + "_" + identifier;
 
 			return Flyway.configure()
 					.configuration(configuration)
 					.locations(locations.toArray(String[]::new))
+					.table(customizedTable)
+					.baselineVersion("0")
+					.baselineOnMigrate(true)
 					.load();
 		}
 	}

spring-modulith-runtime/src/test/java/org/springframework/modulith/runtime/flyway/SpringModulithFlywayCustomizerUnitTests.java

@@ -46,7 +46,9 @@ public class SpringModulithFlywayCustomizerUnitTests {
 	@TestFactory // GH-1067
 	Stream<DynamicTest> augmentsLocationWithApplicationModuleIdentifier() {
 
-		var expected = List.of(List.of("classpath:db/migration/first"), List.of("classpath:db/migration/second"));
+		var expected = List.of(
+				List.of("classpath:db/migration/first"),
+				List.of("classpath:db/migration/second"));
 
 		var twoIdentifiers = List.of("first", "second");
 		var singleIdentifier = List.of("identifier");
@@ -58,10 +60,12 @@ Stream<DynamicTest> augmentsLocationWithApplicationModuleIdentifier() {
 		var mixedLocation = List.of("classpath:db/foo", "classpath:db/migration/**");
 
 		var first = new Fixture(twoIdentifiers, noLocation, expected);
-		var second = new Fixture(singleIdentifier, wildcardLocation, List.of(wildcardLocation));
+		var second = new Fixture(singleIdentifier, wildcardLocation,
+				List.of(List.of("classpath:db/migration/**")));
 		var third = new Fixture(singleIdentifier, multipleLocations,
 				List.of(List.of("classpath:db/first/identifier", "classpath:db/second/identifier")));
-		var fourth = new Fixture(singleIdentifier, mixedLocation, List.of(mixedLocation));
+		var fourth = new Fixture(singleIdentifier, mixedLocation,
+				List.of(List.of("classpath:db/foo/identifier", "classpath:db/migration/**")));
 		var fifth = new Fixture(fullyQualifiedIdentifier, noLocation,
 				List.of(List.of("classpath:db/migration/fully/qualified")));
 
@@ -93,33 +97,36 @@ public void execute() throws Throwable {
 			var result = new SpringModulithFlywayCustomizer(configure.load())
 					.augment(createIdentifiers(identifiers));
 
-			var numberOfFlywayInstances = hasWildCardLocation() ? 1 : identifiers.size() + 1;
+			var numberOfFlywayInstances = identifiers.size() + 1;
+			var expectedRootLocations = locations.isEmpty()
+					? List.of("classpath:db/migration/__root")
+					: locations.stream()
+							.map(it -> it.endsWith("*") ? it : it + "/__root")
+							.toList();
 
-			assertThat(result).hasSize(numberOfFlywayInstances).satisfies(it -> {
+			assertThat(result)
+					.hasSize(numberOfFlywayInstances)
+					.satisfies(it -> {
 
-				// Keeps original migration first
+						// Keeps original migration first
 
-				assertThat(it).element(0)
-						.extracting(Flyway::getConfiguration)
-						.extracting(Configuration::getLocations, as(InstanceOfAssertFactories.ARRAY))
-						.extracting(Object::toString)
-						.containsAll(locations.isEmpty() ? List.of("classpath:db/migration") : locations);
+						assertThat(it).element(0)
+								.extracting(Flyway::getConfiguration)
+								.extracting(Configuration::getLocations, as(InstanceOfAssertFactories.ARRAY))
+								.extracting(Object::toString)
+								.containsAll(expectedRootLocations);
 
-				// Has added expected additional migrations
+						// Has added expected additional migrations
 
-				for (int i = 1; i < expected.size(); i++) {
+						for (int i = 0; i < expected.size(); i++) {
 
-					var customized = it.get(i);
+							var customized = it.get(i + 1);
 
-					assertThat(customized.getConfiguration().getLocations())
-							.extracting(Location::toString)
-							.containsAll(expected.get(i - 1));
-				}
-			});
-		}
-
-		private boolean hasWildCardLocation() {
-			return locations.stream().anyMatch(it -> it.endsWith("*"));
+							assertThat(customized.getConfiguration().getLocations())
+									.extracting(Location::toString)
+									.containsAll(expected.get(i));
+						}
+					});
 		}
 
 		private static ApplicationModuleIdentifiers createIdentifiers(List<String> identifiers) {

src/docs/antora/modules/ROOT/pages/runtime.adoc

@@ -113,8 +113,14 @@ As of Spring Modulith 2.0, we support the execution of module-specific https://d
 Application modules are encouraged to define migrations for their own persistent data only, which means that these migrations have to be executed in the order of the module dependency tree.
 
 Assume a default Flyway setup with migrations located in `classpath:db/migration`, two application modules `first` and `second` (with `second` depending on `first`), and an activated `spring.modulith.runtime.flyway-enabled` xref:appendix.adoc#configuration-properties[configuration property].
-With that in place we will augment the configured migration to run the default one first, followed by one for `classpath:db/migration/first` and one for `classpath:db/migration/second`.
 
-By selecting which folder to place the migration files in, you can differentiate migrations always to be run from ones that will only get executed for the corresponding module. The application module test integration will only execute the default migration and the ones for modules included in the test run.
+With that in place we will customize the Flyway setup as follows:
+
+- The root migration folder will be changed to `db/migration/__root`. For that, the default version tracking table will be used.
+- Additional migrations for `db/migration/${moduleIdentifier}` will be registered with a tracking table of `flyway_schema_history_${moduleIdentifier}`.
+These migrations are also set up to a baseline version of 0 and set up to baseline on migrate.
+- Migration locations ending in a wildcard will not be customized.
 
-We will not augment migration runs including wildcard expressions in the migration location definition.
+Note, that he version numbers used in migration scripts are now effectively scoped to the application module and should not use global ordering.
+
+By selecting which folder to place the migration files in, you can differentiate migrations always to be run from ones that will only get executed for the corresponding module. The application module test integration will only execute the default migration and the ones for modules included in the test run.