How to Set Up Flyway in Spring Boot with PostgreSQL

Flyway is one of the simplest ways to manage database versioning in Spring Boot. Instead of manually tracking SQL changes (which gets messy fast), Flyway handles migrations automatically in a structured way.

Here’s how you set it up with PostgreSQL.

1. Add Dependencies

Add the required Flyway dependencies in your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-flyway</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

2. Disable Hibernate Auto Schema Update

If Hibernate is auto-creating or updating tables, turn it off. Otherwise, Flyway becomes useless noise on top of Hibernate fighting your schema.

spring.jpa.hibernate.ddl-auto=none

3. Configure Flyway in application.properties

If your migration scripts are placed inside:

src/main/resources/db/migrations

Then configure Flyway like this:

spring.flyway.url=jdbc:postgresql://localhost:5432/databasename
spring.flyway.user=user
spring.flyway.password=password
spring.flyway.enabled=true
spring.flyway.locations=classpath:db/migrations
spring.flyway.baseline-on-migrate=true
spring.flyway.baseline-version=1

4. When to Use Baseline Settings

These two lines matter only in specific cases:

spring.flyway.baseline-on-migrate=true
spring.flyway.baseline-version=1

Use them when:

• You already have an existing database
• Tables/data already exist
• You want Flyway to start tracking from now onward

You can skip them when:

• You are starting a fresh project
• No existing schema/data exists

5. Create Your First Migration File

Inside your migration folder, create a SQL file like:

V1__init.sql

Naming rule matters:

• V1 → version number
• __ → separator (mandatory)
• init → description (you can name it anything meaningful)

Example:

V1__create_user_table.sql

This file becomes your baseline migration.

6. How Flyway Executes Migrations

When the application starts:

• Flyway scans db/migrations

• Detects V1__init.sql
• Marks it as baseline (if configured)
• Executes all new migrations in order

From the next change onward, you just add:

V2__add_orders_table.sql
V3__alter_user_table.sql

Flyway will automatically apply them in sequence.

7. What is Repeatable Migration (R__ files)?

Along with versioned migrations (V1__, V2__, etc.), Flyway also supports repeatable migrations, which start with R__.

Unlike versioned scripts, repeatable migrations:

• Do NOT run once and lock forever
• Re-run automatically whenever the file content changes
• Are mainly used for data seeding or view/procedure updates

Example:

R__insert_default_shifts.sql

INSERT INTO shift(name, start_time, end_time)
VALUES ('DAY_SHIFT', '05:00:00', '12:00:00');

If you later modify it:

INSERT INTO shift(name, start_time, end_time)
VALUES ('EVENING_SHIFT', '16:00:00', '21:00:00');

Key Difference (simple truth)

• V__ = schema evolution (tables, columns, constraints) → runs once, never again
• R__ = repeatable logic (seed data, views, functions) → runs again when changed

Final Result

Once configured properly:

• No manual schema tracking
• No guessing what changed in DB
• Clean version-controlled migrations
• Predictable database state across environments