Spring Boot with DB Migration

Here, I write how to build application in Spring Boot with DB Migration. I use Kotlin and Harmonica, Kotlin database migration library.


  • Kotlin 1.3.20
  • Spring Boot 2.1.2
  • Harmonica 1.1.17
  • PostgreSQL
  • IntelliJ IDEA
  • JDK 11 (You can use JDK 8 or later)

Prepare Application Base

First, let’s generate application base on Spring Initializr.

Choose the following component.

  • Gradle
  • Kotlin
  • Spring Boot 2.1.2

Leave the project meta data as it is.

Add the following dependencies.

  • Web
  • PostgreSQL
  • JPA
  • Thymeleaf

In old articles, I used kotlinx.html for template, but this time I use Thymeleaf, because most people are familiar with it.

Click “Generate Project” button and extract the zip file, then you can see the file structure as follows.

Prepare PostgreSQL

Here is the database configuration.

Database name demo
User name develoepr
Password developer
Database port 5432 (Default Port)

If you don’t have PostgreSQL, you can prepare it with docker as follows.

If you want to change the listening port, please change the first 5432 to another port number.

Open the Project in IntelliJ IDEA

From the “File” menu, click “Open”, and choose the file, “settings.gradle“. You will see the dialog that asks whether you open it as a project or not. Then, please click “Open as a Project” button.

After that you will see the dialog for importing, then configure it and click “OK” button.

Well, let’s change the Kotlin version. Open build.gradle and change Kotlin version to 1.3.20.


Add Module

Let’s add the module. In the Project tool window, choose top directory. From the “File” menu, select “New” and “Module”, the you’ll see “New Module” dialog. On the dialog, please choose “Gradle” in the left pane, and choose “Kotlin (Java)” in the right pane, and click “Next” button.

Next, please configure as follows, and click “Next” button and add the module.

Add as module to demo
GroupId com.example (Inherit)
ArtifactId db
Version 0.0.1-SNAPSHOT (Inherit)

Auto syncronization will work and you may get the following error output.

Now, open db/build.gradle and remove the version of the Kotlin plugin and add libraries.


Set up the db and directory configuration.

Add the next expression to the bottom of build.gradle.

Next, execute the following command.

And create file db/src/main/kotlin/com/example/demo/db/config/Default.kt as follows.

Add and Execute Migration

Now, let’s add the migration. Execute the next command.

Then, you can see the file db/src/main/kotlin/com/example/demo/db/migration/Mxxxxxxxxxxxxxxxxxx_CreateTask.kt. Change it as follows.

Execute migration as follows.

You can see the output like follows.

See the Database

Let’s see the database with psql.

harmonica_migration table contains the executed migration versions. task table is what we wanted to create and task_id_seq sequence is the sequence for task table, which is created automatically.

task table has id column, which is added automatically, and it uses the sequence.

Build Application

From now on, create Spring Boot application. Let’s create files in the follwong structure.

Add configuration

Update application.properties and DemoApplication class.

Add database configuration to the application.properties.

Add @EnableJpaAuditing annotation to DemoApplication class. It is used for timestamp auto updating.


Create an entity, which represents the record in the database. Create the file of the class , Task, as domain/task/Task.kt.

@EntityListeners, @CreateDate and @LastModifiedDate are added for auto updating.


Create the repository interface, TaskRepository, for Task, as domain/task/TaskRepository.kt.

View template

Create the view template, which is resources/templates/task/index.html.


Create the controller, TaskController, as presentation/task/TaskController.kt.

Run the application

Execute ./gradlew bootrun, and after awhile, you can see the page on the browser. Please access to http://localhost:8080/task. And you can add and remove tasks.

Figure: 2 tasks are added.

The code of this demo project is on GitHub.