To keep track of which migrations have already been applied when and by whom, Flyway adds a special schema history table to your schema. You can think of this table as a complete audit trail of all changes performed against the schema. It also tracks migration checksums and whether or not the migrations were successful.

Location

The name of Flyway's schema history table can be customized using table.

The schema in which to create the table can be configured using defaultSchema.

The tablespace in which to create the table can be configured using tablespace.

Migration States

Info

You can view view the status information of all your migrations against a particular database by running the info command (used under the hood by Flyway Desktop).

Info lets you know where you stand. At a glance you will see which migrations have already been applied, which other ones are still pending, when they were executed and whether they were successful or not.

Validate

You can validate migrations applied to a target database against the migrations in your project using the validate command.

This is very useful to detect accidental changes that may prevent you from reliably recreating the schema.

Custom validation rules

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. Flyway Teams Edition provides the flexibility to do this.

Learn more about custom validate rules

Repair

Flyway will return errors if migrations do not match the expected state in schema history. This will happen if:

• Versioned migration checksum does not match schema history checksum record - this is usually a result of migrations being edited after being applied to the database
• Versioned migrations present in the schema history table no longer able to be located

If the changes to the migrations are intentional, the schema history table will need to be repaired, using the repair command, which resets the schema history

The createSchemas option and the Schema History Table

Flyway requires a schema for the schema history table to reside in before running a migration. When createSchemas is false, it will be impossible for the schema history table to be created, unless a schema already exists for it to reside in.

So, given a configuration like this:

flyway.createSchemas=false
flyway.schemas=my_schema

The following can happen if createSchemas is false:

• Run migrate
• my_schema is not created by Flyway
• Because my_schema is the default schema, Flyway attempts to create the schema history table in my_schema
• my_schema does not exist, so the operation fails

Therefore, when toggling createSchemas to false, the following setup is recommended:

• Set the default schema to flyway_history_schema
  • Either by setting defaultSchema, or placing it first in the schemas configuration option
• Set initSql to create flyway_history_schema if it doesn't exist
• Place your other schemas in the schemas property

So, given a configuration like this:

flyway.createSchemas=false
flyway.initSql=CREATE IF NOT EXISTS flyway_history_schema
flyway.schemas=flyway_history_schema,my_schema

The following will happen:

• Run migrate
• initSql is executed, so flyway_history_schema is created
• Because flyway_history_schema is the default schema, Flyway attempts to create the schema history table in flyway_history_schema
• my_schema is not created by Flyway
• Migrations run as normal
• Migrations are free to control creation of my_schema