Spring Boot Configuration Properties Migrator

1. Introduction

In this tutorial, we’ll explore a support system provided by Spring to facilitate Spring Boot upgrades. In particular, we’ll be looking at the spring-boot-properties-migrator module. It helps migrate application properties.

With each Spring Boot version upgrade, there may be properties that are either marked as deprecated, have gone out of support, or were newly introduced. Spring publishes the comprehensive changelog for each upgrade. However, these changelogs can be a bit tedious to go through. That’s where the spring-boot-properties-migrator module comes to the rescue. It does so by providing us with personalized information for our setup.

Let’s see this in action!

2. Demo Application

Let’s upgrade our Spring Boot application from version 2.3.0 to 2.6.3.

2.1. Properties

In our demo application, we have two properties files. In the default properties file, application.properties, let’s add:

spring.resources.cache.period=31536000
spring.resources.chain.compressed=false
spring.resources.chain.html-application-cache=false

For the dev profile YAML file application-dev.yaml:

spring:
  resources:
    cache:
      period: 31536000
    chain:
      compressed: true
      html-application-cache: true

Our properties files contain several properties that have either been replaced or removed between Spring Boot 2.3.0 and 2.6.3. Additionally, we also have both .properties and .yaml files for a better demonstration.

2.2. Adding the Dependency

Firstly, let’s add the spring-boot-properties-migrator as a dependency in our module:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-properties-migrator</artifactId>
    <scope>runtime</scope>
</dependency>

If we’re using Gradle, we can add:

runtime("org.springframework.boot:spring-boot-properties-migrator")

The scope of the dependency should be runtime.

3. Running the Scan

Secondly, let’s package and run our application. We’ll be using Maven to build and package:

mvn clean package

Finally, let’s run it:

java -jar target/spring-boot-properties-migrator-demo-1.0-SNAPSHOT.jar

As a result, the spring-boot-properties-migrator module scans our application properties files and works its magic! More on that in a bit.

4. Understanding the Scan Output

Let’s go through the logs to understand the scan’s recommendations.

4.1. Replaceable Properties

For the properties that have a known replacement, we see WARN logs from the PropertiesMigrationListener class:

WARN 34777 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that have been renamed was found in the environment:

Property source 'Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'':
	Key: spring.resources.cache.period
		Line: 2
		Replacement: spring.web.resources.cache.period
	Key: spring.resources.chain.compressed
		Line: 3
		Replacement: spring.web.resources.chain.compressed

Property source 'Config resource 'class path resource [application-dev.yaml]' via location 'optional:classpath:/'':
	Key: spring.resources.cache.period
		Line: 5
		Replacement: spring.web.resources.cache.period
	Key: spring.resources.chain.compressed
		Line: 7
		Replacement: spring.web.resources.chain.compressed


Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

We see all the key information in the logs, such as which property file, key, line number, and replacement key pertains to each entry. This helps us easily identify and replace all such properties. Additionally, the module replaces these properties with available replacements at runtime, allowing us to be able to run the application without having to make any changes.

4.2. Unsupported Properties

For the properties that don’t have a known replacement, we see ERROR logs from the PropertiesMigrationListener class:

ERROR 34777 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that are no longer supported was found in the environment:

Property source 'Config resource 'class path resource [application.properties]' via location 'optional:classpath:/'':
	Key: spring.resources.chain.html-application-cache
		Line: 4
		Reason: none

Property source 'Config resource 'class path resource [application-dev.yaml]' via location 'optional:classpath:/'':
	Key: spring.resources.chain.html-application-cache
		Line: 8
		Reason: none

Like the previous scenario, we see the offending property file, the key, the line number in the property file, and the reason behind the key being removed. But, unlike in the previous scenario, the startup of the application may fail depending on the property in question. We might also face runtime issues since these properties couldn’t be migrated automatically.

5. Updating the Configuration Properties

Now, with the crucial information provided to us by the scan, we’re in a much better state to upgrade the properties. We know the property file to go to, the line number, and the key to either replace with the suggested replacement or consult the release notes for the specific keys that have no replacement.

Let’s fix our properties files. In the default properties file, application.properties, let’s replace the properties as per the recommendation:

spring.web.resources.cache.period=31536000
spring.web.resources.chain.compressed=false

Similarly, let’s update the dev profile YAML file application-dev.yaml:

spring:
  web:
    resources:
      cache:
        period: 31536000
      chain:
        compressed: false

To summarize, we’ve replaced the properties spring.resources.cache.period with spring.web.resources.cache.period and spring.resources.chain.compressed with spring.web.resources.chain.compressed. The spring.resources.chain.html-application-cache key is no longer supported in the new version. Hence, we’ve removed it in this case.

Let’s once again run the scan. First, let’s build the application:

mvn clean package

Then, let’s run it:

java -jar target/spring-boot-properties-migrator-demo-1.0-SNAPSHOT.jar

Now, all the information logs we saw earlier from the PropertiesMigrationListener class disappear, indicating that our properties migration is successful!

6. How Does All This Work? A Peek Under the Hood

A Spring Boot Module JAR contains a spring-configuration-metadata.json file in the META-INF folder. These JSON files are the sources of the information for the spring-boot-properties-migrator module. When it scans our properties files, it pulls the relevant properties’ metadata information from these JSON files to build the scan report.

An example from the file shows the various information that we see in the generated reports:

In spring-autoconfigure:2.6.3.jarMETA-INF/spring-configuration-metadata.json, we’ll find the entry for spring.resources.cache.period:

{
    "name": "spring.resources.cache.period",
    "type": "java.time.Duration",
    "deprecated": true,
    "deprecation": {
        "level": "error",
        "replacement": "spring.web.resources.cache.period"
    }
}

Similarly, in spring-boot:2.0.0.RELEASE.jar META-INF/spring-configuration-metadata.json, we’ll find the entry for banner.image.location:

{
    "defaultValue": "banner.gif",
    "deprecated": true,
    "name": "banner.image.location",
    "description": "Banner image file location (jpg\/png can also be used).",
    "type": "org.springframework.core.io.Resource",
    "deprecation": {
        "level": "error",
        "replacement": "spring.banner.image.location"
    }
}

7. Caveats

Before we wrap this article, let’s go over some of the caveats with the spring-boot-properties-migrator.

7.1. Don’t Keep This Dependency in Production

This module is meant to be used only during the upgrades in development environments. Once we identify the properties to be updated or removed and then correct them, we can remove the module from our dependencies. Eventually, we should never include this module in higher environments. It’s not recommended due to certain costs associated with it.

7.2. Historical Properties

We shouldn’t jump the versions during upgrades because the module may not be able to detect the really old properties deprecated in the much older versions. For example, let’s add banner.image.location to our application.properties file:

banner.image.location="myBanner.txt"

This property was deprecated in Spring Boot 2.0. If we try to run our application with Spring Boot version 2.6.3 directly, we won’t see any warning or error message regarding it. We’d have to run the scan with Spring Boot 2.0 to be able to detect this property:

WARN 25015 --- [           main] o.s.b.c.p.m.PropertiesMigrationListener  : 
The use of configuration keys that have been renamed was found in the environment:

Property source 'applicationConfig: [classpath:/application.properties]':
    Key: banner.image.location
	Line: 5
	Replacement: spring.banner.image.location


Each configuration key has been temporarily mapped to its replacement for your convenience. To silence this warning, please update your configuration to use the new keys.

8. Conclusion

In this article, we explored the spring-boot-properties-migrator. It’s a handy tool that scans our properties file and gives easily actionable scan reports. We also looked at the high-level view of how the module achieves its feat. Finally, to ensure this tool’s best utilization, we went over a few caveats.