Flyway

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:

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