In this article, which is a continuation of a Flyway series we will learn how to add Flyway to an existing Spring Boot Project.

If you are not sure what this tool can bring to your project, then check out my first post on Flyway with Spring Boot, where you can find all the necessary information.

2. Project Setup

This time, we won’t spend time preparing a sample project (well, if you are here then there’s a 95% chance that you already have some project).

Nevertheless, if you don’t have one, but still would like to learn how to add a flyway to an existing Spring Boot project, then no worries. You can find an example project in this GitHub repository.

Note: If you use the project from the linked repository, then please run the script.sql file (can be found in /resources/sql directory) against your database, before you start the application.

3. Strategy For Adding Flyway To Existing Spring Boot Project

Before we start anything, I just wanted to emphasize that we should always create a backup, before performing any operations on our databases. Regardless of how widely used, or well-tested the tool is, something can always go wrong and we have to be ready to roll out plan B.

3.1 Add Flyway Dependency

As the first thing (after the backup!), let’s add the necessary dependency to our Spring Boot project.

For gradle, it will look as follows:

implementation 'org.flywaydb:flyway-core:9.8.3'

On the other hand, when working with Maven, we need to add these lines:

<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
  <version>9.8.3</version>
</dependency>

3.2 Verify Spring Boot App

Nextly, let’s run our Spring Boot application and verify, whether anything changed:

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'flywayInitializer' defined in class path resource [org/springframework/boot/autoconfigure/flyway/FlywayAutoConfiguration$FlywayConfiguration.class]: Found non-empty schema(s) "custom_schema" but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.
at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.initializeBean(AbstractAutowireCapableBeanFactory.java:1751) ~[spring-beans-6.0.2.jar:6.0.2]

As we can clearly see, Flyway throws a pretty descriptive message:

Found non-empty schema(s) “custom_schema” but no schema history table. Use baseline() or set baselineOnMigrate to true to initialize the schema history table.

And basically, this error clearly states what we need to do when adding a Flyway to an existing project. But before that, we have to take care of a couple of things.

3.3 Generate Production Database DDL

Firstly, we have to generate an SQL script containing the DDL our production database, including:

• procedures
• views,
• triggers etc…

I won’t go into details here, because DDL script generation depends on the database you are using. Nevertheless, it can be done pretty easily with tools like DataGrip, DBeaver, or pg_dump.

And when the SQL script with DDL is ready, let’s save it in the Flyway migrations directory (in Spring Boot the default one is resources/db/migration). Of course, we have to remember about the Flyway files naming convention, so the file name should be something, like V1__my_custom_init_script.sql.

3.4 Clear Irrelevant Data

If you have only one database instance in your project, then feel free to skip this point. Otherwise, we have to make sure that the generated DDL script will work in every other environment. And we can achieve it in two ways:

• if we don’t care about the data in other environments- then we can run the Flyway clean command.
• however, if we do actually care about the data in our non-production environments, then there’s no other choice than to manually verify and align other database structures with the main one.

The choice here is yours and will depend on many factors, like the importance of test data, amount of environments, etc.

Nevertheless, if you would like to clean your database before adding a Flyway to your existing project, then you can do that with the following:

flyway -defaultSchema="custom_schema" \
  -url="jdbc:postgresql://{URL}:{PORT}/{DB_NAME}" \
  -cleanDisabled="false" \
  -user="{USERNAME}" \
  clean

Please keep in mind that with this command, we will be prompted to enter the password manually (and alternatively, we can pass the -password flag).

3.5 Add Flyway To Existing Spring Boot Project

Finally, with all that being done, we can return to the Spring Boot project and make the necessary changes.

Let’s navigate to the application.yaml file and insert these settings:

spring:
  flyway:
    baselineOnMigrate: true
    defaultSchema: "custom_schema" # not necessary, but most likely you'll want to point to a specific schema

As we can see, with baselineOnMigrate set to true, we instruct Flyway to automatically call baseline when migration is executed against a non-empty schema. Additionally, we set the defaultSchema value, but this is totally optional.

As a result, the flyway_schema_history table is added to our schema:

and populated with precisely one record.

Please remember that the baselineOnMigrate set to true is only required once- when we do the initial deployment and can be removed after that.

3.6 Add Flyway Using Commands

Basically, with all of the above being done we are finished and can enjoy the benefits of Flyway in our project.

However, if you would like to learn how to add Flyway to an existing project using CLI, then you can do exactly the same with the following command:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-baselineOnMigrate="true" \
-locations="filesystem:." migrate

Or, alternatively, run baseline only:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-locations="filesystem:." baseline

And then the migrate command:

flyway -defaultSchema="custom_schema" \ 
-url="jdbc:postgresql://{HOST}:{PORT}/{DB_NAME}" \
-user="USERNAME" \
-locations="filesystem:." migrate

These commands might be useful if you would like to extract migrations to a separate directory (and/or repository).

4. Add Flyway To An Existing Spring Boot Project Summary

And that would be all in this article about how to add Flyway to an existing Spring Boot project. If you’d like to get to know Flyway better, then I highly encourage you to visit their documentation.

Let me know in the comments section in case of any questions 🙂

The post Add Flyway To An Existing Spring Boot Project appeared first on Codersee blog- Kotlin on the backend.

In this short article, I would like to show you how to configure Flyway when working with Spring WebFlux and Spring Data R2DBC.

In my previous tutorial, we’ve learned a lot about Flyway itself and how to set it up correctly, when working with Spring Boot. Nevertheless, if we would like to apply this knowledge when building a reactive web application with Spring WebFlux and Spring Data R2DBC, we would have to take a different approach. And that’s what we are going to focus on in this tutorial.

2. Imports

2.1. Create Spring WebFlux With R2DBC Project

As the first step, let’s create a skeleton project. We can do so by simply going to the Spring Initializr page and selecting the following dependencies:

• Spring Reactive Web
• Spring Data R2DBC
• PostgreSQL Driver

After that, we should see the following in our build.gradle.kts file:

implementation("org.springframework.boot:spring-boot-starter-data-r2dbc")
implementation("org.springframework.boot:spring-boot-starter-webflux")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor")
runtimeOnly("org.postgresql:postgresql")
runtimeOnly("org.postgresql:r2dbc-postgresql")

// other dependencies

2.2. Add Flyway Dependency

Unfortunately, we can’t add the Flyway dependency to our Spring WebFlux project on the same page, so we have to do it manually:

implementation("org.flywaydb:flyway-core:8.5.11")

With that being done, we have to reload Gradle changes and wait till the additional dependency is fetched to our environment.

3. Configure application.properties (or YAML) File

As the next step, let’s head to the application.properties file (or application.yaml in my case) and configure database connection along with Flyway:

spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/
    username: postgres
    password: password
  flyway:
    url: jdbc:postgresql://localhost:5432/
    user: postgres
    password: password

Please keep in mind that the values used for port, username, and password may be different in your case. Moreover, in the case of the Flyway connection, we have to use JDBC.

4. Implement Flyway Migration

Nextly, let’s prepare an SQL file, which we would like to run as the first migration. Let’s call it V1__My_First_Migration.sql:

CREATE TABLE person(
  id SERIAL NOT NULL PRIMARY KEY,
  email TEXT NOT NULL
);

As we can see, this simple script will create a new table called person. Please remember to put this file in the correct directory- resources/db/migration/ in our case.

5. Add Flyway Configuration For R2DBC

As the next step, let’s run our application to see if our Flyway migration is working. Technically, the app started successfully. Nevertheless, logs do not contain anything about applied migration and when we check the database we can clearly see, that migration was not run.

To change that, let’s add a FlywayConfiguration file to our project:

@Configuration
class FlywayConfiguration(private val env: Environment) {

    @Bean(initMethod = "migrate")
    fun flyway(): Flyway {
        return Flyway(Flyway.configure()
            .dataSource(
                env.getRequiredProperty("spring.flyway.url"),
                env.getRequiredProperty("spring.flyway.user"),
                env.getRequiredProperty("spring.flyway.password"))
        )
    }
}

Alternatively, we can use @Value annotation, as well:

@Configuration
class FlywayConfiguration(
    @Value("\${spring.flyway.url}") private val url: String,
    @Value("\${spring.flyway.user}") private val user: String,
    @Value("\${spring.flyway.password}") private val password: String
) {

    @Bean(initMethod = "migrate")
    fun flyway(): Flyway {
        return Flyway(
            Flyway.configure()
                .dataSource(url, user, password)
        )
    }
}

As we can see, this configuration is responsible for creating a new Flyway bean with the URL, username, and password obtained from our application.yaml file.

If we rerun our app once again, we will see the following:

Creating Schema History table "public"."flyway_schema_history" ...
Current version of schema "public": << Empty Schema >>
Migrating schema "public" to version "1 - My First Migration"
Successfully applied 1 migration to schema "public", now at version v1 (execution time 00:00.034s)

The above message clearly indicates that the migration was run and we can expect a new table in our database.

6. Summary

And that would be all for this short article on how to configure Flyway migrations with Spring WebFlux and R2DBC.

Let me know if you found this material useful in the comment sections below, or by using the contact form.

Finally, if you would like to see the whole source code, please refer to this GitHub repository.

The post Flyway Migrations With Spring WebFlux (R2DBC) appeared first on Codersee blog- Kotlin on the backend.

In this blog post, I would like to show you what exactly Flyway is and how to configure it, when working with Spring Boot.

Together, we will spend some time to figure out:

• why do we even need it in our project?
• how can we quickly configure Flyway with Spring Boot?
• finally, how can we customize its behavior?

2. What is Flyway and What Problems Does It Solve?

To put it simply, Flyway is a database versioning tool. Just like Git is a version control system for our codebase, Flyway takes care of database schema management.

Let’s imagine that we’ve started a Spring Boot project, which communicates with the PostgreSQL database. We’ve been working on our own, implementing new features, adding new tables, and changing the schema many times. At some point, a new programmer joins our team, so we simply export our local or remote database and send him the script, so that he will be able to set up a local environment.

So far so good, but what will happen when more people join our team? Or we would like to create more testing environments? Of course, we could save the script and update it each time, we change anything, but this can introduce plenty of problems, for example:

• when multiple people are editing schema asynchronously, how can we make sure that all their scripts are applied in a specific environment?
• how can we be sure that all developers have exactly the same (or a specific) version on their local?
• how can we determine the correct order of scripts, so that nothing breaks when applying them?

If you are not convinced after reading the above points, then imagine working without Git when cooperating with others and exchanging written code manually 🙂 Technically- doable- nevertheless definitely not recommended.

Of course, Flyway is not the only tool we could use with Spring Boot, however, it is definitely easy to work with.

[elementor-template id=”9007393″]

3. Setup Flyway With Spring Boot

With all of that being said, let’s switch to the practice part. If you would like to simply download the skeleton for this tutorial, I’ve uploaded it to this GitHub repository. Nevertheless, I highly encourage you to set up the Spring Boot project on your own and follow below steps. This way, you’re definitely gonna learn more.

3.1. Imports

As the first step, let’s add the necessary imports:

implementation("org.flywaydb:flyway-core:10.13.0")
runtimeOnly("org.flywaydb:flyway-database-postgresql:10.13.0")
implementation("org.postgresql:postgresql:42.7.3")
implementation("org.springframework.boot:spring-boot-starter-data-jdbc") //alternatively, we could use spring-boot-starter-data-jpa

The above 4 are the bare minimum required to work with Flyway and Spring Boot.

3.2. Edit Application Properties

As the next step, we have to make sure that we’ve set up the database connection properly.

The easiest way to do so is via application.yaml (or application.properties) file:

spring:
  datasource:
    url: "jdbc:postgresql://localhost:5432/your-db-name"
    username: db-username
    password: db-password

By default, Flyway will use the @Primary Data Source (which we’ve configured above).

3.3. Add Migrations Directory

Nextly, we have to add /db/migration directory to the /resources. If we don’t do so and try to run the application, it will fail with the following error:

Flyway failed to initialize: none of the following migration scripts locations could be found:

classpath:db/migration

Of course, we can customize that, and we will learn how to do that later.

3.4. Validation

For now, let’s check if our setup is working correctly (please make sure that you have a database with an empty schema up and running).

After we run the application, we should see the following in the logs:

Flyway Community Edition 8.5.11 by Redgate
...
Successfully validated 0 migrations (execution time 00:00.009s)
No migrations found. Are your locations set up correctly?
Creating Schema History table "public"."flyway_schema_history" ...
Schema "public" is up to date. No migration necessary.

Moreover, we can see that a new table called flyway_schema_history was added to our schema.

In brief, Flyway uses this table to manage versions and control applied, modified or added scripts. If you would like to see more theory, then this article from their documentation is a great source for that.

3.5. Add a Migration

Finally, let’s add our first migration file called V1__Create_User_Table.sql. This “strange” filename is the default Flyway naming convention, which consists of:

• a prefix– B for baseline, R for repeatable,  U for undo, and V for versioned migrations
• migration number– number 1 in our case. If we would like it to be 1.1, then we should start the name with V1_1
• double underscore– separates version from migration description
• description– underscores are translated to spaces, so our migration will become Create User Table

With that being said, let’s add an example SQL script:

CREATE TABLE IF NOT EXISTS app_user (
  id SERIAL NOT NULL PRIMARY KEY,
  name TEXT NOT NULL
);

After that, let’s run our Spring Boot application once again and check out printed logs:

Migrating schema "public" to version "1 - Create User Table"

As can be seen, migration was applied successfully and a new table was added to our database.

4. Flyway Customization With application.properties

4.1. Enable/Disable Flyway

By default, Flyway is enabled when added to Spring Boot. Nevertheless, if we would like to change that, we can set the enabled flag:

spring:
  flyway:
    enabled: false

4.2. Set Custom Migrations Directory

As I’ve mentioned earlier, the default directory is /db/migration, but it can be customized with spring.flyway.locations property:

spring:
  flyway:
    locations: "classpath:my-custom-dir,classpath:my-custom-dir-2"

As we can see, we can provide multiple directories. When working with Spring Boot, a classpath means resources directory. Alternatively, we can refer to any directory in the system using filesystem instead.

It’s worth mentioning that when we specify multiple directories, then at least one of them has to exist (but not all of them). Moreover, we can’t duplicate migration versions among our directories.

So, in practice:

/resources
    /my-custom-dir
        V2__one.sql
    /my-custom-dir-2
        V1__one.sql

These two directories are treated, just like one and if we would specify V1 version twice, then the FlywayException would be thrown:

Found more than one migration with version 1

4.3. Vendor Aware Directory

Additionally, Flyway allows us not only to specify hard-coded paths, but we can use a vendor placeholder, which will be resolved on the fly:

spring:
  flyway:
    locations: "classpath:my-custom-dir/{vendor}"

With the above config, Flyway will look for migrations files inside the /resources/my-custom-dir/postgresql directory. You can find a full list of supported vendors right here.

5. Flyway Java (Kotlin) Configuration

It’s worth mentioning that Flyway allows us to apply migrations written in Java. When working with Spring Boot, they will be auto-configured with any bean implementing a JavaMigration interface. However, this interface requires us to implement a few methods, so the recommended way is to extend the BaseJavaMigration abstract class instead (and sufficient in most cases).

Given that, let’s have a look at the example written in Kotlin (which technically does not differ too much from its Java counterpart):

@Component
class V1__Create_User_Table : BaseJavaMigration() {
    override fun migrate(context: Context) {
        val update = context.connection.createStatement()
        update.execute(
            """
            CREATE TABLE IF NOT EXISTS app_user (
                id SERIAL NOT NULL PRIMARY KEY, 
                name TEXT NOT NULL
            );
            """.trimIndent()
        )
    }
}

@Component
class V2__Drop_User_Table : BaseJavaMigration() {
    override fun migrate(context: Context) {
        val update = context.connection.createStatement()
        update.execute("DROP TABLE app_user;")
    }
}

As we can see, the only thing we have to do is to override the migrate method, and that class names should follow the default Flyway naming convention.

If you are wondering whether we can mix SQL files with Spring Beans configuration, then the answer is yes (however we should be really cautious about it).

6. Flyway With Spring Boot Summary

And that would be all for this tutorial about Flyway With Spring Boot. I believe the knowledge presented here will be sufficient to easily incorporate this tool into any Spring Boot project. Moreover, if you’d like to learn how to incorporate Flyway to an existing Spring Boot project, or how to use it with Spring WebFlux, then check out the flyway tag.

Let me know what you think about database version control tools. Do you like Flyway, or maybe you prefer some other tool?

Have a great day and see you in the next articles! 🙂

The post Flyway Migrations With Spring Boot appeared first on Codersee blog- Kotlin on the backend.