Flyway is a database migration tool that makes it easy to manage the evolution of your database schema. With Flyway, you can track, version, and repeatably deploy database changes with ease. In this blog post, we'll take a look at how Flyway works and what are the different elements of Flyway migration scripts and how they are used to manage your database schema.
Flyway works by reading migration scripts from a designated location and applying them to the database in the order specified by their version numbers. It keeps track of which scripts have been executed, and can roll back changes if necessary.
SQL statements for creating, altering, and deleting database objects such as tables, views, and stored procedures.
Comments describing the changes made by each migration script.
Version numbers and descriptions to uniquely identify each migration script and track which scripts have been executed.
Pre- and post-migration scripts to perform tasks such as data validation and cleanup.
Placeholders to allow for dynamic content such as environment-specific configuration.
Repeatable migrations, which are scripts that can be run multiple times without causing errors.
Clean-up commands to remove or undo the changes made by the migration.
1. SQL statements for creating, altering, and deleting database objects
These statements are used to make changes to the database schema, such as creating new tables, modifying existing ones, and deleting unnecessary objects. For example, a migration script might contain the following SQL statements to create a new table called "users" with columns for user id, name, and email:
2. Comments describing the changes made by each migration script.
Comments are used to provide context and explain what changes are being made by each migration script. For example, a migration script might include the following comment to explain that it is adding a new column to the "users" table:
3. Version numbers and descriptions to uniquely identify each migration script and track which scripts have been executed
Flyway uses version numbers to keep track of which migration scripts have been executed, and to ensure that they are executed in the correct order. The version number is usually in the format of "Vx.x.x__" at the start of the migration script file name and it's used to uniquely identify the migration. For example, "V1.2.3__create_users_table.sql"
4. Pre- and post-migration scripts
These scripts are used to perform tasks before and after a migration is executed. For example, a pre-migration script might be used to backup the current state of the database, while a post-migration script might be used to update application-specific data.
5. Placeholders to allow for dynamic content such as environment-specific configuration
Placeholders are used to make migration scripts more flexible by allowing for dynamic content, such as environment-specific configuration. For example, a migration script might use a placeholder to reference the name of a specific schema, which can be replaced with the appropriate value at runtime.
6. Repeatable migrations
These are scripts that can be run multiple times without causing errors. This is useful for situations where the migration logic needs to be changed or updated, but the initial data is still accurate. For example, if a repeatable migration is adding a column to a table, and it already exists then it will not throw any error.
7. Clean-up commands
These commands are used to remove or undo the changes made by the migration. It's useful in situations where the migration has to be rolled back. For example, if a migration has created a table.
How Flyway works for Gradle and Maven
Gradle :
In order to use Flyway with Gradle, you will need to add the Flyway plugin to your build.gradle file and configure it to point to your migration scripts.
For Example : plugins {
id 'org.flywaydb.flyway' version '7.1.1'
}
flyway {
url = 'jdbc:postgresql://localhost:5432/mydb'
user = 'myuser'
password = 'mypassword'
locations = ['filesystem:src/main/resources/db/migration']
}
The above configuration sets up the Flyway plugin to connect to a PostgreSQL database at localhost on port 5432, using the specified user and password. It also specifies that migration scripts can be found in the src/main/resources/db/migration directory.
To run the Flyway migrations using Gradle, you can use the flywayMigrate task:
For Example :
gradle flywayMigrate-i
./gradlew flywayMigrate
Maven :
For Maven, you will need to add the Flyway plugin to your pom.xml file and configure it to point to your migration scripts.For Example :
<build>
<plugins>
<plugin>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-maven-plugin</artifactId>
<version>7.1.1</version>
<configuration>
<url>jdbc:postgresql://localhost:5432/mydb</url>
<user>myuser</user>
<password>mypassword</password>
<locations>
<location>filesystem:src/main/resources/db/migration</location>
</locations>
</configuration>
</plugin>
</plugins>
</build>
To run the Flyway migrations using Maven, you can use the flyway:migrate goal:
For Example :
mvn flyway:migrate
Both above examples are using the same database and migration script location but the commands are different, you can use the one that you are more familiar with.
plugins {
id 'org.flywaydb.flyway' version '7.1.1'
}
flyway {
url = 'jdbc:postgresql://localhost:5432/mydb'
user = 'myuser'
password = 'mypassword'
locations = ['filesystem:src/main/resources/db/migration']
}
The above configuration sets up the Flyway plugin to connect to a PostgreSQL database at localhost on port 5432, using the specified user and password. It also specifies that migration scripts can be found in the src/main/resources/db/migration directory.
To run the Flyway migrations using Gradle, you can use the flywayMigrate task:
gradle flywayMigrate-i
./gradlew flywayMigrate
Maven :
For Maven, you will need to add the Flyway plugin to your pom.xml file and configure it to point to your migration scripts.
For Example :
<build>
<plugins>
<plugin>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-maven-plugin</artifactId>
<version>7.1.1</version>
<configuration>
<url>jdbc:postgresql://localhost:5432/mydb</url>
<user>myuser</user>
<password>mypassword</password>
<locations>
<location>filesystem:src/main/resources/db/migration</location>
</locations>
</configuration>
</plugin>
</plugins>
</build>
To run the Flyway migrations using Maven, you can use the flyway:migrate goal:
For Example :
mvn flyway:migrate
Both above examples are using the same database and migration script location but the commands are different, you can use the one that you are more familiar with.
