When developing an application, the database structure rarely stays the same.
At the beginning of a project, you might have only a users table. A few weeks later, you may need to add an email column, create a products table, introduce new relationships, or modify existing constraints.
But here's a problem:
How do you make sure every developer and every environment has the same database structure?
Manually executing SQL queries every time a database changes can quickly become difficult to manage. It becomes even more complicated when working with a team or deploying an application across development, testing, and production environments.
This is where Flyway comes in.
In this article, we'll explore what Flyway is, why developers use it, how database migrations work, and how to integrate Flyway into a Spring Boot application.
1. What Is Flyway?
Flyway is an open-source database migration and version control tool that helps developers manage changes to database schemas over time.
In simple terms, Flyway allows you to manage database changes using SQL scripts called migrations.
Instead of manually executing SQL queries whenever your database structure changes, you create migration files, and Flyway automatically detects and executes them in the correct order.
For example, imagine you're developing an e-commerce application.
Initially, your database contains:
- Users
- Products
- Categories
Later, your application needs:
- Orders
- Payments
- Delivery information
With Flyway, you can create separate migration files for each database change. Flyway tracks which migrations have already been executed and applies only the pending ones.
This makes database changes more organized, predictable, and consistent.
2. Why Do We Need Flyway?
Let's understand the problem without a database migration tool.
Imagine three developers working on the same project.
- Developer A creates a new
productstable. - Developer B adds a
pricecolumn to the products table. - Developer C modifies the table to include product descriptions.
If everyone manually updates their local database, there is a possibility that their database structures will become different.
The same problem can happen when deploying an application to staging or production.
Without proper database version control, developers may face:
- Missing database columns or tables.
- Inconsistent database structures across environments.
- Forgotten SQL changes during deployment.
- Difficulty identifying when and why a database changed.
- Errors caused by unexpected schema differences.
Flyway solves these problems by keeping database changes in version-controlled migration scripts.
Key benefits of Flyway
1. Database version control
Every database change is stored in a migration file and can be tracked through Git.
2. Automatic migrations
Flyway automatically identifies pending migrations and executes them in version order.
3. Consistency across environments
The same migration scripts can be executed in development, testing, staging, and production.
4. Migration history
Flyway maintains a special table called flyway_schema_history to track executed migrations.
5. Team collaboration
Developers can share migration files through a Git repository instead of manually sharing SQL queries.
3. Understanding How Flyway Works
Before implementing Flyway, let's understand its basic workflow.
Flyway follows a simple process:
- Developers create SQL migration files.
- Flyway scans the configured migration directory.
- It checks the database migration history.
- It identifies migrations that haven't been executed.
- It executes pending migrations in the correct order.
- It records successful executions in the migration history table.
For example, imagine you have three migration files:
V1__create_users_table.sql
V2__create_products_table.sql
V3__add_product_price.sql
When Flyway runs for the first time, it executes all three migrations in order.
When you later introduce another migration:
V4__create_orders_table.sql
Flyway executes only V4 because the previous migrations have already been applied.
You don't need to manually track which SQL scripts have been executed.
That's one of the most useful features of Flyway.
4. Understanding Flyway Migration Naming Conventions
Flyway uses a specific naming convention to identify migration files.
The standard format for a versioned SQL migration is:
V{version}__{description}.sql
Let's break it down:
-
V– Indicates a versioned migration. -
version– A unique version number. -
__– Two underscores separating the version and description. -
description– A short explanation of the database change. -
.sql– The SQL file extension.
For example:
V1__create_users_table.sql
V2__create_products_table.sql
V3__add_product_price.sql
V4__create_orders_table.sql
Important: Each version number must be unique. Flyway executes versioned migrations in numerical order, and each is applied only once.
You should also avoid modifying an existing migration after it has been applied to a shared or permanent environment. Create a new migration instead.
5. How to Use Flyway with Spring Boot
Now let's implement Flyway in a Spring Boot application.
For this example, we'll use:
- Java
- Spring Boot
- Maven
- PostgreSQL
- Flyway
You can also use MySQL or other supported relational databases with the appropriate database-specific configuration.
Step 1: Add Flyway Dependencies
Open your Spring Boot project's pom.xml file.
Add the Flyway dependencies:
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-core</artifactId>
</dependency>
<dependency>
<groupId>org.flywaydb</groupId>
<artifactId>flyway-database-postgresql</artifactId>
</dependency>
You'll also need the PostgreSQL JDBC driver if it isn't already included:
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
Spring Boot's dependency management can manage compatible dependency versions for you.
Step 2: Configure Your Database
Open your application.yml file.
Configure your database connection and Flyway:
spring:
datasource:
url: jdbc:postgresql://localhost:5432/my_database
username: postgres
password: your_password
flyway:
enabled: true
locations: classpath:db/migration
Here:
-
datasource.urldefines the database connection. -
usernameandpasswordprovide database credentials. -
flyway.enabledenables Flyway. -
flyway.locationstells Flyway where to find migration files.
Make sure your database exists and the credentials are correct.
For production applications, use environment variables or a secrets manager instead of hardcoding credentials.
Step 3: Create the Migration Directory
Inside your Spring Boot project, create the following directory:
src/
└── main/
└── resources/
└── db/
└── migration/
This is Flyway's default migration location when using Spring Boot.
Now create your first migration file:
V1__create_users_table.sql
Your project structure should look like this:
src/
└── main/
└── resources/
└── db/
└── migration/
├── V1__create_users_table.sql
├── V2__create_products_table.sql
└── V3__create_orders_table.sql
Step 4: Write Your First Migration
Open V1__create_users_table.sql.
Add the following SQL:
CREATE TABLE users (
id BIGSERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(150) NOT NULL UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
This migration creates a users table with:
- An automatically generated ID.
- A name column.
- A unique email address.
- A creation timestamp.
Save the file.
Step 5: Create Another Migration
Now let's create a products table.
Create:
V2__create_products_table.sql
Add:
CREATE TABLE products (
id BIGSERIAL PRIMARY KEY,
name VARCHAR(150) NOT NULL,
description TEXT,
price DECIMAL(10, 2) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
This migration creates a products table.
Notice that we didn't modify the previous migration file. We created a completely new migration.
This is an important practice when working with Flyway.
Step 6: Run Your Spring Boot Application
Now start your Spring Boot application.
Using Maven:
./mvnw spring-boot:run
When Spring Boot starts, Flyway automatically:
- Connects to the configured database.
- Checks for the migration history table.
- Creates
flyway_schema_historyif necessary. - Detects available migration scripts.
- Executes pending migrations.
- Records their execution details.
If everything works correctly, your database should now contain:
users
products
flyway_schema_history
You don't need to manually execute the SQL scripts.
Flyway handles the migration process for you.
6. What Is the flyway_schema_history Table?
One important concept you should understand is the flyway_schema_history table.
This is a special table automatically created and maintained by Flyway.
It stores information about migrations that have been executed.
For example:
| installed_rank | version | description | success |
|---|---|---|---|
| 1 | 1 | create users table | true |
| 2 | 2 | create products table | true |
It also stores additional information, including migration types, checksums, execution times, and installation timestamps.
Why is this important?
Imagine you restart your Spring Boot application.
Will Flyway execute V1 and V2 again?
No.
Flyway checks the migration history table and recognizes that these migrations have already been executed successfully.
It only executes new pending migrations.
This prevents the same versioned migration from being applied repeatedly.
7. What Happens When the Database Structure Changes?
Let's say your application now needs to store product stock quantities.
You want to add a new column called stock_quantity to the products table.
Instead of modifying the existing V2 migration, create a new file:
V3__add_stock_quantity_to_products.sql
Add the following SQL:
ALTER TABLE products
ADD COLUMN stock_quantity INTEGER DEFAULT 0;
Restart your Spring Boot application.
Flyway detects V3 as a new migration and executes it.
Your products table now has an additional column.
This is how you can continuously evolve your database without losing track of previous changes.
8. Useful Flyway Commands
Flyway provides several commands that help developers manage database migrations.
Here are some commonly used commands:
| Command | Purpose |
|---|---|
migrate |
Applies pending migrations. |
info |
Displays migration status and history. |
validate |
Checks migration consistency and checksums. |
repair |
Repairs migration history metadata in supported scenarios. |
baseline |
Marks an existing database as being at a specified version. |
For example, if you're using the Flyway Maven plugin, you can execute:
./mvnw flyway:info
To validate migrations:
./mvnw flyway:validate
To execute pending migrations:
./mvnw flyway:migrate
The Maven plugin must be configured in your project to use these Maven goals.
For most Spring Boot applications with Flyway auto-configuration, you don't need to manually run the migrate command every time. Spring Boot automatically triggers migrations during application startup.
9. Best Practices When Using Flyway
Here are some important practices to follow when working with Flyway in real-world projects.
1. Never modify applied migrations
Once a migration has been applied to a shared environment, avoid changing its contents.
Create a new migration for additional changes.
2. Use meaningful migration names
Instead of:
V1__update.sql
V2__changes.sql
Prefer:
V1__create_users_table.sql
V2__add_email_to_users.sql
V3__create_products_table.sql
3. Keep migrations small and focused
Each migration should ideally represent one logical database change.
4. Commit migration files to Git
Migration files should be part of your application's source code.
This ensures every developer and deployment environment uses the same migration history.
5. Test migrations before production deployment
Always test your migration scripts against a development or staging database before applying them to production.
6. Be careful with destructive changes
Operations such as dropping tables or deleting columns can permanently remove data.
Plan these changes carefully and take appropriate backups.
7. Use validation
Flyway validation helps detect unexpected changes to migration files, including checksum mismatches.
It is especially useful in team-based development environments.
10. Flyway vs. Manually Executing SQL Scripts
You might wonder why we need Flyway when we can execute SQL queries directly.
The main difference is how database changes are organized and tracked.
| Manual SQL execution | Flyway |
|---|---|
| Developers execute scripts manually. | Migrations can run automatically. |
| Tracking executed scripts is manual. | Migration history is maintained automatically. |
| Different environments may become inconsistent. | The same migration sequence can be applied across environments. |
| Changes may be forgotten during deployment. | Version-controlled migrations provide a clear deployment history. |
| No built-in migration checksum validation. | Flyway validates migration checksums. |
For small applications, manual SQL scripts might seem manageable.
However, as your application grows and more developers become involved, using a migration tool becomes increasingly valuable.
Conclusion
Database changes are an unavoidable part of software development. As applications grow, managing those changes manually becomes more difficult and error-prone.
Flyway simplifies this process by allowing developers to manage database changes through version-controlled migration scripts.
With Spring Boot integration, you can automatically execute pending migrations whenever your application starts, maintain a consistent database structure, and track the history of every database change.
If you're building a Spring Boot application or working on a team-based project, learning Flyway is a valuable skill.
The key takeaway: Instead of treating database changes as manual tasks, treat them as part of your application's source code and deployment workflow.
Happy coding! 🚀
Useful Resources
Top comments (0)