Import fails when multiple applications share the same `mongockChangeLog` collection

[Celmas]

Import fails when multiple applications share the same mongockChangeLog collection

Description

When migrating from Mongock to Flamingock, the application fails at startup with the following error if multiple applications historically shared the same mongockChangeLog audit collection:

OperationException: importing change with id[<changeId>] from database. It must be imported to a flamingock stage

This happens because Flamingock's MongockImporterMongoDB reads all documents from mongockChangeLog without filtering by the current application's classpath. When it encounters a changeLogClass that belongs to a different application (and therefore does not exist on the current classpath), it fails instead of skipping the unknown entry.

Environment

• Java 21
• Spring Boot 3.5.8
• Flamingock 1.2.1
• MongoDB (shared database across multiple microservices)

Steps to reproduce

1. Set up two Spring Boot applications (app1 and app2) sharing the same MongoDB database and using the same mongockChangeLog collection.
2. Run both applications with Mongock so that both write audit entries to the shared collection.
3. Migrate app1 to Flamingock with @MongockSupport.
4. Start app1.

Expected behavior

Flamingock should skip audit entries whose changeLogClass is not found on the current application's classpath, logging a warning rather than throwing an exception. Only entries that belong to the current application should be imported.

Actual behavior

Flamingock throws an OperationException and the application fails to start:

OperationException: importing change with id[APP-5678] from database. It must be imported to a flamingock stage

Suggested fix

In MongockImporterMongoDB, when processing audit entries, catch ClassNotFoundException (or check classpath availability before processing) and skip entries whose class is not found on the current classpath with a WARN-level log message, for example:

WARN: Skipping Mongock audit entry [changeId=APP-5678, class=com.example.app2.changelog.OtherChange] — class not found on classpath. This entry likely belongs to a different application sharing the same audit collection.

This would make Flamingock resilient to the shared-collection pattern without requiring manual data migration.

[dieppa]

Hi @Celmas,

Thanks for the detailed report. We have reviewed the scenario and the root cause is clear.

The problem comes from the fact that several independent applications were historically sharing the same Mongock audit collection (mongockChangeLog). That means the collection contains audit entries produced by different applications, with different changelog classes and different classpaths.

In Mongock this could work because the validation was more relaxed, but it was not the recommended setup. Each independent application should have its own Mongock repository/audit collection. In Mongock this can be configured by using a different repository name per application.

Flamingock is stricter during the import process. When importing Mongock entries, it expects the imported audit entries to correspond to changes available in the current application. In your case, application app1 loads audit entries that actually belong to app2, but those classes are not part of app1's classpath. As a result, Flamingock cannot map those entries to Flamingock changes and fails the import validation.

So the correct target model is:

• each application should use its own Flamingock audit store;
• each application should only import the Mongock entries that belong to that same application;
• independent applications should not share the same audit history.

That said, we understand that this situation may affect other teams migrating from Mongock, especially because Mongock allowed this pattern in practice even though it was not the right model.

For that reason, we will add support for a migration/import option that relaxes this validation during the Mongock import process. This will allow users to handle this kind of legacy shared-collection scenario explicitly.

However, this option should be used carefully. Once the validation is relaxed, the responsibility moves to the user to ensure that each application migrates only the relevant audit history and ends up with its own dedicated Flamingock audit store.

In practice, the migration should look like this:

1. Start from the legacy shared Mongock collection.
2. Configure each application with a different Flamingock audit store / repository name.
3. Enable the relaxed import option during migration.
4. Let each application import only the entries that correspond to its own changes.
5. After migration, keep one audit store per application.

So this is not something we consider the ideal runtime model, but we agree Flamingock should provide a safe migration path for existing Mongock users who are already in this situation.

We will work on this and include the fix in the next minor version, 1.4.0.

Thanks again for reporting it.

[Celmas]

Hello @dieppa !

Do you have any ETA for fix? We are still waiting for 1.4.0 version.
Thank you in advance

[dieppa]

Hi @Celmas,

Thanks for following up, and apologies for the wait.

The fix is in. 1.4.0-rc.1 was published today, and we are planning the 1.4.0 GA release for Monday, barring any surprises in the final validation pass.

As discussed above, the change introduces a new opt-in option on @MongockSupport: ignoreUnknownEntries. When set to true Flamingock switches the Mongock import to a relaxed mode in which audit entries that do not correspond to any change in the current application's Flamingock pipeline (precisely the entries
written by app2 in your shared-collection scenario) are skipped during import instead of failing the startup.

A minimal configuration for your case:

  @MongockSupport(
      targetSystem = "mongodb-target-system",
      ignoreUnknownEntries = "true"
  )
  public class Application { }

A couple of notes worth keeping in mind:

• The option only takes effect when skipImport is false, which is your case. You need the import to bring app1's legitimate Mongock history over.
• This is a tolerance mechanism for legacy shared-origin scenarios, not the recommended long-term model. As the docs note, the expected target state is that each application owns its own audit origin; a dedicated MongoDB collection in your case. We would recommend, once this migration is in place, configuring
  each application's Flamingock audit store against its own collection so that the boundary between applications is clean going forward.

The full description, including how ignoreUnknownEntries interacts with the other Mongock-import fields (skipImport, origin, emptyOriginAllowed), is in the Coming from Mongock. Optional configuration (https://docs.flamingock.io/resources/coming-from-mongock#optional-configuration) section of the documentation. This will be available in the documentation, once the version 1.4.0 is published.

If it helps your timeline, you can already validate against 1.4.0-rc.1 on Maven Central; otherwise 1.4.0 will be available on Monday. Either way, we will keep this issue open until you confirm the migration completes cleanly on your side. Please do not hesitate to come back here if anything else surfaces.

Thanks again for the original report.

[dieppa]

Hi @Celmas ,

Released in stable version 1.4.0.

This includes the fix previously available in 1.4.0-rc.1.

Closing this issue, but please reopen/comment if the problem persists.