Customize validation rules with ignoreMigrationPatterns
Published 12 July 2023
Flyway can validate your migrations according to its own conventions, giving you the confidence you need to apply new migrations. However, as the lifetime of a project increases, there will inevitably be hotfixes, deleted migrations and other changes that break the conventions of Flyway's validation.
In these cases you need a way to tell Flyway that these migrations are valid, and in Flyway Teams Edition 7.8.1 we added the ignoreMigrationPatterns
configuration parameter that let's you achieve this!
How to use ignoreMigrationPatterns
You can read about how to configure ignoreMigrationPatterns
here
In summary, ignoreMigrationPatterns
allows you to specify a list of patterns of the form <code>type:status</code> and any migration that matches any of these patterns is ignored during validate.
That's all there is to it! After quick and easy configuration you'll have customized how Flyway validates your migrations!
Let's see this in action with some examples.
Examples
Ignore only missing repeatable migrations
Let's say our schema history table is as follows:
+------------+---------+-------------+------+--------------+---------+----------+
| Category | Version | Description | Type | Installed On | State | Undoable |
+------------+---------+-------------+------+--------------+---------+----------+
| Versioned | 1 | first | SQL | ... | Success | No |
| Repeatable | | repeatable | SQL | ... | Missing | |
+------------+---------+-------------+------+--------------+---------+----------+
We have a successfully applied versioned migration V1 and a missing repeatable migration, repeatable
. Running flyway validate will fail, giving us an error that there is a Detected applied migration not resolved locally
. In most cases this is the correct result; you identify why this migration is missing, such as being accidentally deleted, and after resolving the issue running flyway validate
again will succeed.
However, what if this migration was deleted intentionally? This can be the case when it is infeasible to keep every migration. In particular you might delete repeatable migrations but not versioned migrations, and you need a way for validate to reflect this.
Giving ignoreMigrationPatterns
the value repeatable:missing
is exactly the way to achieve this! Running flyway validate
will no longer fail, and missing versioned migrations will still get caught.
Ignore both missing repeatable migrations and pending versioned migrations
This time let's assume our schema history table is as follows:
+------------+---------+-------------+------+--------------+---------+----------+
| Category | Version | Description | Type | Installed On | State | Undoable |
+------------+---------+-------------+------+--------------+---------+----------+
| Repeatable | | repeatable | SQL | ... | Missing | |
| Versioned | 1 | first | SQL | | Pending | No |
+------------+---------+-------------+------+--------------+---------+----------+
We have a missing repeatable migration repeatable
as in the previous example, and a pending versioned migration, V1. Running flyway validate
will fail for both of these migrations, erroring that there is a Detected applied migration not resolved locally
and Detected resolved migration not applied to database
While the default behavior of validate here causes an error, you may not want to error in this scenario. Missing repeatable migrations were explained in the previous example, and if you are validating before applying new migrations then you don't want to fail on any pending migrations. Instead, you want to ensure that migrations that were applied up to now can be successfully validated.
Achieving the desired result only requires passing a list of patterns to ignoreMigrationPatterns
with the value repeatable:missing,*:pending
.
flyway validate
will no longer fail for missing repeatable migrations or any pending migrations, which we specified using the *
wild card.
How can I validate specific migrations?
You can specify classes of migration type
and migration status
to ignore during validate using ignoreMigrationPatterns
, but what if you need to precisely validate specific migrations? We can achieve this by combining ignoreMigrationPatterns
with cherryPick
For this last example, assume our schema history table is as below:
+-----------+---------+-------------+------+--------------+---------+----------+
| Category | Version | Description | Type | Installed On | State | Undoable |
+-----------+---------+-------------+------+--------------+---------+----------+
| Versioned | 1 | first | SQL | ... | Missing | No |
+-----------+---------+-------------+------+--------------+---------+----------+
We have a missing versioned migration V1 and running flyway validate
will fail as in the first example, but what if we don't want this specific migration to cause a failure? This can arise when you have hotfixes that are subsequently removed.
In order to validate specific migrations, we first need to specify those migrations to cherryPick
. Then any pattern specified to ignoreMigrationPatterns
will only apply to those migrations in cherryPick
Setting the value of cherryPick
to 1 and ignoreMigrationPatterns
to versioned:missing
will ensure that if the migration with version 1 is missing
, it won't cause a validation failure.
Running flyway validate
will now succeed!
Note: When running flyway validate
with cherryPick
set, any migration not specific to cherryPick
is automatically ignored during validation and will need to be validated separately
Try it out!
Now that you’ve seen how to customize your validate
workflows, give it a go! Existing Flyway Teams users can try this out today!
If this is something that interests you the start your free trial here!
Originally published 21st April 2021 on Flywaydb.org