Learn Microservices Book: Spring Boot 2.7 Upgrade Guide

A new upgrade chapter! This one covers the required changes on the Learn Microservices with Spring Boot book’s source code to update it to Spring Boot 2.7.1 and some extras.

An H2 major upgrade surprise and some extras

Smooth upgrades couldn’t last for too long. This upgrade breaks the book’s code sources again, but nothing that can’t be fixed with some minor changes.

This release of the book sources also prepares the road for the upcoming Spring Boot 3.x major upgrade.

In summary, these are the changes covered in this chapter:

• (Mandatory) Fix the error caused by using incompatible H2 features
• (Mandatory) Fix the error caused by using a reserved H2 keyword
• (Optional) Migrate to the new configuration system introduced in Spring Boot 2.4
• (Optional) Use an H2 database server to avoid data isolation while scaling up the system
• (Optional) Use the macOS’ Netty DNS resolver to avoid ugly warnings in logs

About this guide: This is a practical approach to migrating a Spring Boot project from version 2.6 to version 2.7. It uses the codebase from the Learn Microservices with Spring Boot book’s practical example, but it applies to other projects too. If you want to dive into how Spring Boot works and set up a complete microservice architecture, get a copy now.

We’ll take as a baseline the last changes to upgrade the projects to Spring Boot 2.6. The new source code is available on GitHub (while you’re there, give it a star!).

Major H2 upgrade

Spring Boot 2.7 brings a major upgrade of the database we use in the book’s code from 1.x to 2.x. Many changes in this major version are backward-incompatible and two of them impact our code (breaking it). See this section in the Spring Boot’s 2.7 release notes for more details.

Feature not supported: “AUTO_SERVER=TRUE && DB_CLOSE_ON_EXIT=FALSE”

In the book, we use the “Auto Server” H2 feature to automatically create a database server when starting a microservice instance. The main goal was to keep the database simple using just files that can be shared across microservice instances. With this feature, multiple microservice replicas can connect to the same database file instead of having independent data stores, which wouldn’t fit into a microservice architecture.

Combined with that feature, we set the flag DB_CLOSE_ON_EXIT=FALSE. I intended to avoid that stopping a microservice would cause the database server to go down. But I misunderstood the docs because that’s not how it works. This flag is only useful when the application needs to do something with the database in its own shutdown hook.

The new major release disallows the usage of these two flags together because that may cause incompatibility issues. See this comment for more details.

We can solve this very quickly: just removing the DB_CLOSE_ON_EXIT parameter from the connection URL.

spring.datasource.url=jdbc:h2:file:~/gamification;AUTO_SERVER=TRUE;

Error executing DDL “create table user …”

If you try to start the multiplication microservice after the upgrade in a new workspace, you’ll get an error like the one below:

Caused by: org.h2.jdbc.JdbcSQLSyntaxErrorException: Syntax error in SQL statement "create table [*]user (id bigint not null, alias varchar(255), primary key (id))"; expected "identifier"; SQL statement: [...]

The error description might not help too much, but the root cause is that our table name is user and this is now a syntax keyword. We must escape it, change the table name or configure H2 to avoid considering this a keyword. To keep it simple, we’ll go for this last option which requires only one change in the database URL in application.properties. We use the NON_KEYWORDS parameter in H2 to achieve this.

spring.datasource.url=jdbc:h2:file:~/multiplication;AUTO_SERVER=TRUE;NON_KEYWORDS=USER;

Bonus: Migrating bootstrap to application’s properties

In addition to the mandatory upgrades to make the code work with 2.7, I also switched to the new configuration approach introduced by Spring Boot 2.4.x. It’s good to do this in preparation for the Spring Boot 3.x release, which will stop working with the old approach.

The required changes to move to the new configuration approach include removing the legacy bootstrap starter and migrating properties from bootstrap files to application properties files.

Summary

That’s all! A couple of mandatory fixes with this upgrade, both caused by the H2 major upgrade, and some bonus content that you can use to keep up-to-date with the Spring Boot changes. On top of that, we now have the option to use an H2 database server, which makes the whole setup even more similar to a real production-ready microservice architecture.

If you still don’t have the book, I strongly recommend you get your copy now. I keep updating the book’s source code and will be sharing more content around the same use case.

Source Code: The book’s source code with all the updates is available on GitHub: U.2.7. While you are there, please give it a star!