This is documented, somewhat, but I wanted to put this down for myself, as the I don’t love the docs and they are hard to sort through.
Flyway is open source software owned and maintained by Redgate, my employer. There are also paid versions with additional features.
The Main Files
There are essentially 4 different types of files you can use for scripts in Flyway. These are:
- versioned scripts
- repeatable scripts
- baseline scripts
- undo scripts
I’ll discuss each of these in light detail below. This isn’t intended to replace the documentation, but give a short explanation of each.
For each type of file, there is a naming standard, which is the same for all. Essentially, there is are four parts. As an example, I’ll use V8.2__add_new_table.sql to explain this. The four parts are:
- The prefix for the type of script, in this case, a V script.
- The version. for my example this is 8.2.
- The separator, always two underscores
- The description, add_new_table, in my case.
- The suffix, which is an extension
Versioned Scripts
These are the V scripts, which are named with a V to start. These are scripts which are run once on each target, and intended to be those that change the schema. The “V” is the default, but this can be configured. I wouldn’t change this.
These are typically the CREATE or ALTER scripts that you run to change objects. You can have as much SQL code in here as you’d like. Think of these as a SQL Compare deploy script. One or my objects changes.
The run once is nice because once you’ve deployed these, you don’t want to run them again. If you write idempotent scripts, you wouldn’t care but most people don’t do that well.
Repeatable Migrations
These are used less in the current Redgate paradigm, but these are repeatable scripts. They are designed to run every time you run “flyway migrate”. Again, the default is an “R” script, but this is configurable. Again, don’t change this.
These scripts don’t have versions because they execute over and over. This could be used for creating or recreating programmable code objects, like view/procedures/functions/packages. They could also be used for places you need to ensure data is always there or has certain values.
These scripts run after the migrate scripts, so be aware of that.
Baseline Scripts
By default, baseline scripts are “B” scripts. This can be changed. These scripts have a database version that you want to start with for some purpose. Like a new development effort or new deployment project.
These are run for new environments only, and usually contain all the base objects you might need. If you start a Flyway project on a database that has objects, put all the code to recreate this state (CREATE objects and add data) in a baseline script.
Undo Scripts
The undo scripts are the “U” scripts. This can be changed, and these should have a version that matches a versioned script. We can run one of these scripts corresponding to those versions to “undo” changes. Since you can’t really undo anything in the database world, these should include code that reverses the action of the V script.
Be careful with these, especially if you run these more than a few minutes after the V script. Flyway isn’t checking that you won’t lose data.
I’d only use these after extensive testing in a pipeline and then only if my deployment broke immediately. These are good for putting in a previous version of a view/proc/function and quickly rolling back.