-
Notifications
You must be signed in to change notification settings - Fork 40.9k
Spring Boot Config Data Migration Guide
This document is meant to help you migrate your application.properties and application.yml files for use with Spring Boot 2.4 and above.
Spring Boot 2.4 has provided an overhaul of the way that application.poperties and application.yml files are processed.
The updated logic has been designed to simplify and rationalize the way that external configuration is loaded.
It has also allowed us to provide new features, such as spring.config.import support.
The updated design intentionally restricts certain property combinations. This means that you may need to change a few things when upgrading from Spring Boot 2.3 or earlier.
If you’re not yet ready to migrate your application to use the new config data processing logic, you’ll need to switch back to the legacy mode.
To do this, you should set the spring.config.use-legacy-processing property to true.
The property needs to be set in the Spring Environment.
The easiest way is usually to to add it to the application.properties or application.yml inside your jar.
For example, you can have a src/main/resources/application.properties as follows:
spring.config.use-legacy-processing=true
# any other propertiesFor many applications, you won’t need to make any changes to your existing properties files.
Specifically, if you only have a single application.properties or application.yml file, you don’t use spring.profiles<.*> properties and you don’t make use of muti-document YAML, then upgrading should just work.
If you do have a more advanced set-up, then you should follow the advice in the rest of this document.
If you use multi-document YAML files (files with ---- separators) then you need to be aware that property sources are now added in the order that documents are declared.
With Spring Boot 2.3 and earlier, the order that the individual documents were added was based on profile activation order.
If you have properties that override each other, you need to make sure that the property you want to "win" is lower in the file. This means that you may need to reorder the documents inside your YAML.
If you use configuration outside of your jar, and you make use of profile specific configuration files, you should check that your properties are loaded as expected.
In earlier versions of Spring Boot, an application.properties file outside of your jar would not override a application-<profile>.properties file inside your jar.
As of Spring Boot 2.4, external file always override packaged files (profile specific or not). You can read more about the rationale for this change in GitHub Issue 3845. You can also check the update documentation which describes the new ordering.
If you use the spring.profiles property, for example in multi-document YAML files, you should migrate to spring.config.activate.on-profile.
As with the previous property, you can specify a list of profiles that need to be active for the properties to apply.
You can also use profile expressions such as (prod & cloud)
You can still use the spring.profiles.active property to activate specific profiles, however, you won’t be able to use this property in combination with spring.config.activate.on-profile.
If you previous used spring.profiles.include in combination with spring.profiles, you should look at the new “profile groups” feature.