Frequently Asked Questions

I found a defect. Where should I report it?

Check the issue tracker if someone else already reported it. If not, raise a new issue.

I have a feature request. Where should I submit it?

Check the issue tracker if someone else already suggested it. If not, raise a new issue.

I have a question. Where can I ask it?

Post your question on StackOverflow under the flyway tag.

What about downgrade scripts/downward migrations?

Flyway does NOT support downgrade scripts.
While the idea of downgrade scripts (popularized by Rails Migrations) is a nice one in theory, unfortunately it breaks down in practice. As soon as you have destructive changes (drop, delete, truncate, ...), you start getting into trouble. And even if you don't, you end up creating home-made alternatives for restoring backups, which need to be properly tested as well.

Downgrade scripts assume the whole migration failed.
A migration can fail at any point. If you have 10 statements, it is possible for the 1st, the 5th, the 7th or the 10th to fail. There is simply no way to know in advance. Downgrade scripts are written to roll back an entire migration. This renders them effectively useless, even for non-destructive changes.

Maintain backwards compatibility between the DB and all versions of the code currently deployed in production.
This way a failed migration is not a disaster. The old version of the application is still compatible with the DB, so you can simply roll back the application code, investigate, and take corrective measures.

A much better solution is a proper, well tested, backup and restore strategy.
It is independent of the database structure, and once it is tested and proven to work, no migration script can break it. For optimal performance, and if your infrastructure supports this, we recommend using the snapshot technology of your underlying storage solution. Especially for larger data volumes, this can be several orders of magnitude faster than traditional backups and restores!

What is the best strategy for dealing with hot fixes?

You have a regular release schedule, say once per sprint. Version 7 is live and you are developing version 8. Version 8 contains DB Schema Changes. Suddenly hot fix is required for version 7, and it also needs a schema change.

How can you deal with this?

Even though the code may be branched, the database schema won't. It will have a linear evolution.

This means that the emergency fix, say version 7.1 needs to be deployed as part of the hot fix AND the new version 8.

By the time version 8 will be deployed, Flyway will recognize that the migration version 7.1 has already be applied. It will ignore it and migrate to version 8.

When recreating the database, everything with be cleanly installed in order: version 7, 7.1 and 8.

If this isn't an option you can activate the outOfOrder property to allow Flyway to run the migrations out of order and fill the gaps.

Can multiple nodes migrate in parallel?

Yes! Flyway uses the locking technology of your database to coordinate multiple nodes. This ensures that even if even multiple instances of your application attempt to migrate the database at the same time, it still works. Cluster configurations are fully supported.

Does Flyway perform a roll back if a migration fails?

Flyway runs each migration in a separate transaction. In case of failure this transaction is rolled back. Unfortunately, today only DB2, PostgreSQL, Derby and to a certain extent SQL Server support DDL statements inside a transaction. Other databases such as Oracle will implicitly sneak in a commit before and after each DDL statement, drastically reducing the effectiveness of this roll back. One alternative if you want to work around this, is to include only a single DDL statement per migration. This solution however has the drawback of being quite cumbersome.

Does Flyway support multiple schemas?

Yes! These are the recommended strategies for dealing with them:

The schemas have the same life-cycle:

Use a single Flyway instance. Flyway has support for this built-in. Fill the flyway.schemas property with the comma-separated list of schemas you wish to manage. All schemas will be tracked using a single metadata table that will be placed in the first schema of the list. Make sure the user of the datasource has the necessary grants for all schemas, and prefix the objects (tables, views, ...) you reference.

The schemas have a distinct life-cycle or must be autonomous and cleanly separated:

Use multiple Flyway instances. Each instance manages its own schema and references its own metadata table. Place migrations for each schema in a distinct location.

Schema foo:

locations = /sql/foo
schemas = foo
table = schema_version

Schema bar:

locations = /sql/bar
schemas = bar
table = schema_version

Does Flyway work with OSGI?

Yes! Flyway runs on Equinox and is well suited for OSGi and Eclipse RCP applications.

Does Flyway support placeholder replacement?

Yes! Flyway can replace placeholders in Sql migrations. The default pattern is ${placeholder}. This can be configured using the placeholderPrefix and placeholderSuffix properties.

Does Flyway depend on Spring?

No. Flyway has zero required dependences.

If you have Spring Jdbc on the classpath, Flyway will be able to load Java migrations making use of Spring's convenient JdbcTemplate class.

Can I make structure changes to the DB outside of Flyway?

No. One of the prerequisites for being able to rely on the metadata in the database and having reliable migrations is that ALL database changes are made by Flyway. No exceptions. The price for this reliability is discipline. Ad hoc changes have no room here as they will literally sabotage your confidence. Even simple things like adding an index can trip over a migration if it has already been added manually before.

How do you repair the database after a failed migration?

If your database supports DDL transactions, Flyway does the work for you.

If your database doesn't, these are the steps to follow:

  1. Manually undo the changes of the migration
  2. Invoke the repair command
  3. Fix the failed migration
  4. Try again

Why does clean drop individual objects instead of the schema itself?

clean will remove what Flyway created. If Flyway also created the schema itself, clean will drop it. Otherwise it will only drop the objects within the schema.

What is the best strategy for handling database-specific sql?

Assuming you use Derby in TEST and Oracle in PROD.

You can use the flyway.locations property. It would look like this:

TEST (Derby): flyway.locations=sql/common,sql/derby

PROD (Oracle): flyway.locations=sql/common,sql/oracle

You could then have the common statements (V1__Create_table.sql) in common and different copies of the DB-specific statements (V2__Alter_table.sql) in the db-specific locations.

An even better solution, in my opinion, is to have the same DB in prod and test. Yes, you do lose a bit of performance, but on the other hand you also eliminate another difference (and potential source of errors) between the environments.

Why is the schema_version table case-sensitive?

The schema_version case-sensitive due to the quotes used in its creation script. This allows for characters not supported in identifiers otherwise.

The name (and case) can be configured through the flyway.table property.

The table is an internal Flyway implementation detail and not part of the a public API. It can therefore can change from time to time.

How can I integrate Flyway with Hibernate in a CDI environment?

This is explained with code in this StackOverflow answer.

Contribute