Conditional migration

[elvislicsari]

Hi,

I would like to be able to run a migration when an external condition is met. Was able to do this using mongock with the runAlways = true on a @ChangeUnit.
Not sure i'm able to achieve this with flamingock out of the box.

So far i tried a @ConditionalOnProperty(name = "run.migration", havingValue = "true") applied on the Change class, but the migration was run anyway.

Tried also the Recovery(strategy = RecoveryStrategy.ALWAYS_RETRY) but the application doesn't start when any exception is being thrown from Apply method.

The last solution that comes to mind, is to start manually Flamingock migration, try/catch some custom ConditionalRetryableException thrown by Apply when condition is not met and continue with the application start-up.
Haven't put this to test yet as i don't really like doing things manually.

Is there any other better approach to achieve this ?

Thanks,
Elvis

[dieppa]

Hi @elvislicsari ,

Thanks for the detailed explanation.

Before suggesting a concrete approach, I would like to understand the use case a bit better, because I’m not fully sure what you are trying to model here.

In Mongock, runAlways = true was mainly intended to execute a change every time the runner starts, independently of whether it had already been executed before. It was not really designed as a conditional execution mechanism, although I can see how it could be used that way if the condition is evaluated inside the change itself.

So I would like to understand your requirement more precisely:

1. What is the external condition you are waiting for? A feature flag? A value in another system? A table/collection existing?...

2. What should happen when the condition is not met? Should Flamingock skip the change and continue the application startup?

3. Is the change expected to run only once when the condition eventually becomes true, or should it run multiple times whenever the condition is true?

This last point is important because those two cases have different semantics.

If the change is expected to run once, then it still behaves like a regular migration/change, just with some kind of external readiness condition.

But if the change is expected to run more than once, then it is not really a normal ordered migration anymore. It becomes more like a recurring/reconciliation task. For example, if you have changes C1, C2, and C3, and C2 can run again later, the audit history may look like:

C1 -> C2 -> C3 -> C2

And if a new change C4 is later added, it could become:

C1 -> C2 -> C3 -> C2 -> C4

That makes the relationship between ordering, audit history, and repeated execution less straightforward. It may still be valid for your use case, but we need to understand whether the order between normal changes and repeated conditional changes matters to you.

The reason I’m asking is that runAlways, conditional execution, retry/recovery, and repeated execution are different concepts:

• runAlways means “execute every time the runner starts”.
• Conditional execution means “execute only when some condition is true”.
• Recovery means “handle an execution that failed or was left incomplete”.
• Repeated conditional execution means “execute again when some condition is true again”, which may need a different execution model.

@ConditionalOnProperty probably does not work as expected here because Flamingock does not rely on Spring bean registration in the same way regular Spring components do. The change metadata is discovered and processed by Flamingock, so a Spring condition on the class may not necessarily prevent Flamingock from seeing and executing the change.

Also, RecoveryStrategy.ALWAYS_RETRY is not intended for this scenario. Recovery is about handling failed or incomplete executions, not about expressing “this change is not ready to run yet”. Throwing an exception to represent an unmet condition would likely make Flamingock treat the change as failed, which is why the application startup does not continue.

Depending on your exact use case, there may be a few possible approaches, but I’d rather not suggest the wrong one before understanding the semantics you need.

Could you share a bit more context about the external condition, whether the change should run once or multiple times, and whether ordering with the rest of the changes matters in your scenario?

Regards,

[elvislicsari]

Hi

Thanks for the answer, let me explain a bit more what i need.

So, we have features that we want them enabled on a certain release on a certain date on a certain environment.
These features might or might not need data migration attached to them (no structure so far, but it might happen as well).
We want these migrations to run when an external condition is met, something like feature-x is enabled.
They should do actual database migration when the condition is met, only once, skipped otherwise.

I think i can already achieve want i need with the current flamingock version.
Was thinking to have a different stage for these conditional migrations (or feature migrations) so they do not impact the other ones.
And also what i said in my previous comment, "start manually Flamingock migration, try/catch some custom ConditionalRetryableException thrown by Apply when condition is not met and continue with the application start-up".

It would be nice if this would come out of the box with flamingock and i would not need to do all that "manual" stuff.
Something like in this picture to give you an idea about my expectations (doesn't need to match reality though :D).

Could insert STARTED, SKIPPED in audit logs when condition is not met.

Thanks,
Elvis

[elvislicsari]

Hi again,

Just a quick update, was able to achieve what i needed.

1. use spring boot integration dependency:

<dependency>
  <groupId>io.flamingock</groupId>
  <artifactId>flamingock-springboot-integration</artifactId>
</dependency>

2. use deferred management in application properties:

flamingock:
    management-mode: deferred

3. use 2 separate stages for main and conditional so they do not impact each other. also instead of conditional, it might be a good idea to use a stage per feature if more than 1 migrations are needed.

@EnableFlamingock(stages = {
    @Stage(location = "stage.for.main.migration"),
    @Stage(location = "stage.for.conditional.migration")
})

4. spring boot lifecyle to manually start the flamigock builder

@Component
@RequiredArgsConstructor
@Slf4j
public class FlamingockReadyEventRunner {

    private final AbstractChangeRunnerBuilder<?, ?> flamingockBuilder;

    @EventListener(ApplicationReadyEvent.class)
    public void onApplicationReady() {

        try {
            log.info("Starting Flamingock migrations");
            flamingockBuilder.build().run();
            log.info("Finished Flamingock migrations");
        } catch (FlamingockException e) {
            if (e.getCause() != null && e.getCause() instanceof RetryableChangeException) {
                log.warn("Flamingock migration failed", e);
            } else {
                log.error("Flamingock migration failed", e);
                throw e;
            }
        } catch (Exception e) {
            log.error("Flamingock migration failed", e);
            throw e;
        }
    }
}

public class RetryableChangeException extends RuntimeException {
    public RetryableChangeException(String message) {
        super(message);
    }
}

5. and lastly, the change

@TargetSystem(id = DB_NAME)
@Change(id = "_0002__FeatureX", author = "cornholio")
public class _0002__FeatureX {

    @Apply
    public void apply(MongoTemplate mongoTemplate, ApplicationContext context) {
        if (!context.getEnvironment().getProperty("feature.enabled", Boolean.class, false)) {
            throw new RetryableChangeException("Feature X is disabled");
        }
        log.info("Feature X is enabled");
    }

    @Rollback
    public void rollback(MongoTemplate mongoTemplate) {

    }
}

[dieppa]

Hello,

I think I understand your case better now, but I would like to dig a bit deeper so we can help with two things:

1. a short-term solution that works with the current Flamingock model, and
2. a possible longer-term feature that supports this use case more natively.

Let me first confirm my understanding.

Your case

You have some changes that should be applied conditionally, depending on external conditions such as environment, release date, feature flag state, or similar.

Your solution in Mongock

You were using runAlways, and inside the change you checked the condition manually.

If the condition was met, the change was applied. If the condition was not met, the change did nothing. Then, on the next Mongock execution, the same runAlways change was evaluated again.

Your current approach in Flamingock

From what I understand, you are using a separatestage for these conditional changes and triggering Flamingock manually(with deferred ) so you can control the lifecycle.

Inside the conditional change, you evaluate the condition. If the condition is not met, you throw a known/custom exception. Then, outside Flamingock, you inspect the exception: if it is that known condition-not-met exception, you allow the application startup to continue; otherwise, you propagate the error.

Please correct me if I misunderstood any part of this.

Questions

1. Are these conditional changes independent from the main ordered execution stage?

2. Is this a common pattern in your team?
   Do you have one or two exceptional conditional changes, or is this something you expect to use frequently?

3. If you have multiple conditional changes in the same stage, do they all depend on the same condition, or can each change have its own independent condition?

4. In Mongock, I understand the runAlways + internal condition check approach for evaluating the change repeatedly until the condition is met.
   However, once the condition becomes true and the change is actually applied, how did you prevent it from being applied again on future executions?
   For example, if the condition is a feature flag that is initially OFF and later becomes ON, I assume it may stay ON afterwards. Since runAlways keeps executing on every run, did you have an additional mechanism to guarantee that the actual change logic was applied only once?

With this information, we can better reason about a practical short-term approach and also whether Flamingock should support this use case more explicitly in the future.

Thanks.

[elvislicsari]

1. Yes, they are completely independent.

2. It's a common pattern for our UI services. We have clients that are asking for features to be dormant. So you could have them enabled today in some lower env, and in 3 months in an upper environment (discrepancy between release cycle and clients requirements).

3. They would have different conditions, like feature-x and feature-y enabled.
   Or they could also depend on one another. If feature-y is being applied and depends on feature-x, feature-y migration should check both toggles.

4. Right, you nailed it 💯. With mongock, after we made sure a feature (with conditional migrations) is enabled everywhere, we remove the runAlways or move the conditional migration to main. It's a latest data update for us, so this works. But i can envision issues with structure and data changes for other systems.

[elvislicsari]

You understood correctly our use case, the mongock solution as well as the flamingock approach.

[dieppa]

Thanks, that clarifies a lot.

A couple more questions:

1. When you mention the discrepancy between release cycles and client requirements, do you mean that this drift between environments is intentional and expected in your workflow?

   In other words, is having different environments temporarily at different feature/data states acceptable for you, or is it something you would ideally like Flamingock to help reduce or make more visible?

2. You mentioned that these conditional changes are independent from the main ordered execution stage. Are they also independent from each other?

   Or could you have multiple conditional changes that still need to be executed in a specific order? If so, please, can you extend a bit more this?: Do they depend on the same condition? Do they depend in different conditions but still the execution of one change must be after another?

Thanks!

[elvislicsari]

1. Yes, it is intentional but i would not expect Flamingock to help reduce or make it more visible. This is something very specific to our use-case, would not bother with it. Was just trying to point out the main reason we need conditional migrations.

2. The way we use these conditional migration is to have them separate per feature. They can run independently on each other but they could also be dependent on one another, for example Feature2 should only be enabled if Feature1 is already enabled.
   If they are independently on each other, then we would use 2 different feature toggles, feature-1.enabled and feature-2.enabled.
   If F2 depends on F1, then we would still use 2 different feature toggles, feature-1.enabled and feature-2.enabled. When enabling F2, because it depends on F1, in the migration specific to F2 we would check also feature-1.enabled.

[dieppa]

OK, from point (2), I understand that you currently control the dependency between conditional changes through the dependency between the features themselves.

For example:

• C1 depends on F1
• C2 depends on F1 && F2

That ensures C2 is only applied when both F1 and F2 are enabled.

However, that does not necessarily guarantee that C2 is applied after C1. It only guarantees that the required feature conditions are true.

That is the distinction I was trying to clarify:

Do you usually have cases where C2 must be executed after C1, regardless of the feature conditions?

Or is it enough for each conditional change to evaluate its own feature/environment conditions independently?

[elvislicsari]

Do you usually have cases where C2 must be executed after C1, regardless of the feature conditions?
No

Or is it enough for each conditional change to evaluate its own feature/environment conditions independently?
Yes

[dieppa]

Thanks @elvislicsari, this is very helpful.

I think we now have enough context to understand the use case properly.

Your scenario makes sense to us, and we agree that it is relevant for Flamingock. Conditional changes tied to feature rollout, environment differences, or client-specific activation are valid use cases, especially when they are independent from the main ordered execution flow.

We will approach this in two steps:

1. Short term: provide a cleaner way for you to keep working with Flamingock without relying on exception-based control flow to represent “condition not met”. The goal here is to make your current approach more comfortable and semantically clearer.

2. Longer term: design a more native Flamingock model for conditional changes. This will likely involve a dedicated execution model where condition-not-met is treated differently from execution failure, and where these changes can be evaluated independently from the main ordered stage.

We still need to refine the exact design and semantics, especially around ordering, dependencies between conditional changes, audit state, and rollback behavior. But your input gives us a very clear direction.

Thanks again for taking the time to explain the scenario in detail. This is exactly the kind of feedback that helps us shape Flamingock properly.