When developing an application, you may need to modify the database schema: add new tables, update existing ones, introduce indexes, and so on.

Migrations help manage these changes in a sequential and organized way, ensuring data integrity and keeping the database schema aligned with the application's code. For migrations, we will be using Flyway.

What is Flyway?

One of the key features of Flyway is its support for migration versioning, allowing you to track changes to the database structure and roll back to previous versions if needed.

Note

Flyway supports a variety of database management systems, such as PostgreSQL, MySQL, Oracle, SQL Server, and others.

Creating a Migration With Flyway

To start, add the Flyway dependency to your Spring Boot project. Since we are using Maven, add the following dependency to your pom.xml file:

We will also add another JPA dependency, which works together with Flyway. We will cover JPA in more detail later.

This dependency will help us integrate Flyway into our project! But that's not all, we still need to configure it!

Of course, Flyway needs to know which database it will be working with, so we need to explicitly specify the database and provide access credentials.

The main configurations can be set in application.properties:

We need to specify the url, user, and password to allow Flyway to work with our database.

However, to avoid entering these values multiple times, we can reference them from other parameters using the ${} syntax.

In the previous chapter, we created a my_database database and added a book table to it. However, we can now delete the book table since it will be created through a migration.

Now everything is ready for us to create our first migration in the application! We need to create a db folder inside the resources directory, and within that folder, create another one named migration. The full path should look like this: src/main/resources/db/migration.

In the migration directory, we can now create files where we will define our changes. The file format should be V<version>__<description>.sql.

Migrations are applied in the order of their versions. The version numbering must be sequential and without gaps. For example, if you have migrations V1__init.sql and V2__add_column.sql, the next migration should be V3__another_change.sql.

Within the migration file, you can write SQL scripts to define the structure of the database, create new tables, columns, etc.

Let's write the script for creating the books table, which we manually created in the previous chapter, in our V1__create_table_books.sql file.

You can also add a parameter to the application.properties file that specifies where the migrations are located, so Flyway knows the exact path to the migration files:

After this, run the application, and you should see the table created with the fields you specified in the migration!

You can no longer modify the first version of the migration. For each change to your table, you will need to create a new migration file and add the new script there!

Why are Migrations Important?

Migrations are necessary for orderly management of changes in the database, preserving history and allowing for rollbacks when needed.

They help synchronize the database structure across different environments such as development, testing, and production, while also automating the update process, reducing the risk of errors, and ensuring that the database schema remains consistent with the application code.

Each migration also documents specific changes, making it easier to understand and maintain the database schema.

Summary

Using Flyway simplifies and automates the process of managing database changes, leading to more reliable and efficient application development.