SpringBoot + Flyway - "Java project from A to Z"

An article from a series about creating a Java project (links to other materials are at the end). Its goal is to analyze key technologies, the result is to write a telegram bot. In this part, we try to launch SpringBoot and Flyway. The minimum amount of theory, as you like))) We omit the final comparison of Flyway/Liquibase for an indefinite period of time and get to the point. And even so it has already dragged on. In order not to describe Flyway twice, I decided to immediately add it to our future JRTB project.

What do we need to do as part of this?

1. Launch a SpringBoot application based on Maven.
2. Add Flyway there: fortunately, they are easily integrated.
3. Add a schema for the tables that we have in the example database.

This way we will learn how to work with Flyway. Why a separate project, and not immediately into our JRTB? Because later, anyone who wants to understand how to do this will have a project with an example and an article that describes working with it. Well, let's go!

What is flyway

To use something, you first need to figure out what it is and why. Flyway is a database version control tool. The words are well-known, but somehow the understanding has not been added, right? Let's try to describe the problem that flyway solves. Let's say we have a project. Like everything in our world, it is not perfect, so it was not possible to plan and draw up the final version of the project. Every time certain unaccounted nuances appear. The project uses a database in its work. Of course, if the project changes, the database structure may also change. Let's say we add a new field for one of the entities in our project. How to do it?

1. Add this field to our entity, update everything so that the business logic works.
2. Update the database. The only possible way is to do it manually. To do this, you need to go in and register the necessary sql script.

The second point raises many questions:

1. But if we have more than one place where we deploy our project, then does this need to be done in each of them?
2. and if we want to go back, how do we know exactly what state the database structure is in now?
3. How will we be sure that the database change was successful?
4. How can I get the opportunity to track all the database changes that took place on the project?

If you do it manually, the answers will not be the best... To avoid all these difficulties, you can use a database migration tool. One of these is Flyway. What is his job? As part of the project, we store separate sql files (so-called migrations), which store everything that we do with the database at one time. All migrations occur strictly in a certain order, which allows you to track changes in the structure and data of the database (often, using migration, test data is added to the project so that when it is deployed to some server, it already has some values ​​​​with which you can test project). After the tests pass, migrations are launched when the project is built. They connect to the database and perform migrations. If migrations have already been carried out on this database, then flyway will simply skip them (it stores data about migrations and their status in a separate table in the database, which helps manage them), and if some migration was unsuccessful, then the project build and its mounting (deployment) to the server will stop. I tried to describe it in as much detail as possible. If everything is still not completely clear, it doesn’t matter: with practice, understanding will come.

Launch SpringBoot + Flyway

What is Spring Boot

What are we launching?... To understand what and why we are doing, you need to decide what SpringBoot is. First, let's quickly (well, very quickly) talk about Spring . At the moment, it is the de facto industry standard in developing server applications in Java. Standard of what? How can I explain this to you? Spring is the skeleton of the application, onto which we then throw the “meat” - our business logic. With the help of Spring (hereinafter I will use this tracing paper so as not to waste time switching languages ​​:D)) Spring gives us a start from which we begin to do everything. It is multi-faceted, multi-modular:

1. Do you want to work with a database? Do you want relational? Do you want non-relational? Here we are with Spring Data.
2. Do you want to work with http requests? Here you go, Spring web (Spring MVC).
3. Do you need a container for all your objects in one place? Here's Spring Core.
4. Do you need to set up security on a project so that there are different roles and chain of command? Spring Security.
5. Just when you thought it would be nice to have such a thing, it turns out that Spring already has what you need, and it integrates quickly and easily.

Therefore, we can say that this is not just a framework (such a huge library), but a whole ecosystem that is developing at a breakneck pace. To understand what Spring Core is, that is, the base to which modules are connected, I advise you to watch a live demo on creating your own framework. It is hosted by Evgeny Borisov, a very cool guy in the field of Java and Spring. Do everything he did, and the work of spring will become more clear to you. SpringBoot, in turn, is the pinnacle of everything they have. The magic of pure water. Minimum settings to make the first launch of the application. Of course, this will not give you an understanding of how to use it and what to do. But before rushing into the depths of development, you need to look at everything from a bird's eye view.

Launching SpringBoot

Since we already understood what Maven is, let's create a new project for our needs. To do this, you just need to go to a website specially created for this matter. It's called Spring Initializr . Here you need to fill out and select what you need:

1. The project build tool is gradle or maven. As you can see, Ant is no longer even mentioned. This is a good hint about which build tools are worth your time.
2. The language you can write in is java, kotlin, groovy. Everything is simple here: they are all JVM-like and easily run Java code. By the way, it’s worth looking at Kotlin. Groovy has frankly become uninteresting (there was a time when they switched to grooves, but it quickly passed).
3. Spring version... Here you need to understand that the versions of the main part of Spring and its modules are consistent.
4. Project data. I have already described these things.
5. We choose which archive will be collected - Jar or War.
6. Well, the Java version of our favorite. And recently there have been a lot of these versions... They waited for years, and now there are two a year.

In our case, we will publish this project in the JavaRush Community organization , so the information about the project will be appropriate:

1. Maven - it’s not for nothing that we talked to you about this earlier.
2. Java is our darling :D
3. Let's take version 2.2.11. Why not the newest one? Because the newer it is, the greater the chance that there may be some bugs there. For us, it doesn’t matter which version, but the older one will be more reliable. Therefore, we choose 2.2.11.
4. Group: com.github.javarushcommunity
5. Artifact: springboot-flyway-demo
6. Name: SpringBoot + Flyway Demo
7. Description: Project demonstrates integration between SpringBoot and Flyway . (Yes, the ability to write documentation is an important part of development :))
8. Package name: com.github.javarushcommunity.springbootflywaydemo . Here they will immediately create a basic package for us with a class that will launch our application.
9. Packaging: Jar
10. Java: 8. Let's not go ahead of the locomotive and take the good old eight. Why not 11? What for? For our example, I don’t see the point.

Now let's add the modules. We need to find integration with Flyway. You can also add something related to MySQL and Spring Data. Let's add another lombok (this is a very necessary thing, just trust me for now :D)) To do this, click on ADD DEPENDENCIES ... and select everything you need: This is how we add Flyway. Lombok... And so on. As a result, we get: Huh... we filled out everything)) Now click GENERATE... and that's it - the archive with the generated project is ready :) There is also such a cool thing as SHARE... , which gives you a link to the page that you just filled out. That is, here is the one I generated . And even if something goes wrong, you can always check using the link. Next, we need to link the created project to the Git repository, so we clone the created springboot-flyway-demo project and download it via IDEA. To do this, you need to open the idea and select File -> New -> Project from Existing Sources... : Now add the URL and click Clone . The next step is to transfer the internals of the generated project inside the one we cloned. Confused? I will show you now. I unzipped it and received the following set of files: These need to be transferred to the cloned project. As in the previous article, let's add pom.xml as a maven project: Now we are interested in looking at what was generated for us. If you open all the folders in src and further, you will see the usual hierarchy in Maven projects, which we discussed in the previous article . For those who haven't read it, read it! It can be seen that we have an Application class, and our SpringBoot application will be launched using it. Thanks to the Maven plugin for SpringBoot, we now have the task we need for Maven, namely spring-boot:run. Where can we find this information? On the right, opening the Maven plate and our project: There will be an error, and we won’t be able to read it, we’ll see something like this: To get more information, for speed we can run the main method of the Application class: And then we’ll see the real reason: Here already There is more information and you can do something with it. What's wrong? We have dependencies associated with the database, and therefore we need to provide settings for connecting to it. To do this, we google and find that we need to add the following configurations to application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/flyway_demo_db
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

We run the main method again and get: Now we need to add at least one migration. To correctly create a migration, you need to take the following template: V<VERSION>__<NAME>.sql Using this template, we will create a migration file named V00001__Create_country_table.sql in the appropriate folder: /src/main/resources/db.migration/ . Let's create a country table in it. Let's take the script from the second article about the database . Before starting, let's go in and create a database for work: flyway_demo_db. Let's do this through MysqlWorkbench: Now we can run the main method again: Everything worked out, but since we don’t have anything in the project yet, it finished working. However, it is clear from the logs ( read what logs are ) that:

1. Successfully connected to the database.
2. The migration has been validated and everything is ok.
3. Flyway has created a table to manage migrations.
4. And what migration 00001 started - the creation of the country was successful.

To check this, you can go and see what is being done in the database. So let's go to our MySQL server and see what's going on with the tables in the flyway_demo_db database: $ USE flyway_demo_db; $SHOW TABLES; As I expected, a migration took place, during which the country table was created and the flyway_schema_history table appeared, which stores information on migrations. Let's go further and see what records there are (and whether there are any at all). $SELECT * FROM flyway_schema_history; Here is the recording, the only one. It contains a lot of interesting data. Version, description of the migration, what type of SQL (and maybe also XML), the name of the script itself, checksum ( this is something like a hashcode, which is used to check whether the migration has changed or not. This is done in case we carried out a migration in the database and then it was corrected: this cannot be done, all changes are made only through a new migration and to prevent this from happening, the check amount monitors this ), user sql name, migration processing date, execution time and result (successful or unsuccessful) . A migration written once should not be changed in the future. Even if there is a defect in it. All changes take place only through a new migration. It is very important. To show what will happen, let's change our script a little and try to run it again. Let's add one entry to the country table in our migration: and run the main method and this is what we get: As I expected, flyway recognized that the script had been changed and did not perform the migration. In some cases, it may actually be necessary to run an updated migration, and in order for flyway to skip this, you need to delete the entry in the flyway_schema_history table and then run the updated migration. This is not normal behavior and should not be so, but you also need to know about this method of solving the problem. We dealt with the first migration. Now I would like to add another migration, with data about countries, as was in the article about the database: file V00002__Add_test_data_to_country.sql And let's run the main method again: From the logs it is clear that before the migration started, the database was in version 00001, so all migrations after this version. Next, version 00002 was launched and was successful. Let's check, or do you already believe me that three records in country will already be in the database?)) I would check, so proof: Something like this. If you run the project again, flyway will simply skip rolling out migrations, since the database fully complies with the required version.

Conclusion

This time we learned how to understand and use a database migration tool in conjunction with SpringBoot. This information is necessary to understand what a database version control tool is, using Flyway as an example. Friends, the source code of the project that I showed is published in our organization on Github . If you like the example, give it a star , and I will understand that my work is useful and really worth continuing. Traditionally, I suggest subscribing to my Github account . Through him I conduct all my work on open source and all those demo projects that invariably accompany my articles. Thanks everyone for reading. Next time we will write our application. There will be some necessary theory on Docker in the future, but we will heavily dilute it with practice.

useful links

Today there are not many useful links. Pay attention to Evgeniy's video, it's really worth it!

1. Website for creating projects on Spring
2. Evgeniy Borisov — Spring builder
3. Documentation in Spring for Flyway

A list of all materials in the series is at the beginning of this article.