:root-docs: https://docs.spring.io/spring-boot/docs/2.5.0
:docs: {root-docs}/reference/html/
:actuator-api-docs: {root-docs}/actuator-api/htmlsingle
:api-docs: {root-docs}/api/org/springframework/boot
:gradle-docs: {root-docs}/gradle-plugin/reference/htmlsingle
:maven-docs: {root-docs}/maven-plugin/reference/htmlsingle

== Upgrading from Spring Boot 2.4


=== SQL Script DataSource Initialization
The underlying method used to support `schema.sql` and `data.sql` scripts has been redesigned in Spring Boot 2.5.
`+++spring.datasource.*+++` properties related to `DataSource` initialization have been deprecated in favor of new `+++spring.sql.init.*+++` properties.
These properties can also be used to initialize an SQL database accessed via R2DBC.



==== `schema.sql` and `data.sql` Files
With Spring Boot 2.5.1 and above, the new SQL initialization properties support detection of embedded datasources for JDBC and R2DBC.
By default, SQL database initialization is only performed when using an embedded in-memory database.
To always initialize a SQL database, irrespective of its type, set `spring.sql.init.mode` to `always`.
Similarly, to disable initialization, set `spring.sql.init.mode` to `never`.



==== Separate Credentials
The new script-based SQL database initialization does not support using separate credentials for schema (DDL) and data (DML) changes.
This reduces complexity and aligns its capabilities with Flyway and Liquibase.
If you require separate credentials for schema and data initialization, define your own `org.springframework.jdbc.datasource.init.DataSourceInitializer` beans.



==== Hibernate and data.sql
By default, `data.sql` scripts are now run before Hibernate is initialized.
This aligns the behavior of basic script-based initialization with that of Flyway and Liquibase.
If you want to use `data.sql` to populate a schema created by Hibernate, set `spring.jpa.defer-datasource-initialization` to `true`.
While mixing database initialization technologies is not recommended, this will also allow you to use a `schema.sql` script to build upon a Hibernate-created schema before it's populated via `data.sql`.



==== Initialization ordering
Beans of {docs}/howto.html#howto.data-initialization.dependencies.depends-on-initialization-detection[certain well-known types], such as `JdbcOperations`, will be ordered so that they are initialized after the database has been initialized.
If you have a bean that works with the `DataSource` directly, annotate its class or `@Bean` method with `@DependsOnDatabaseInitialization` to ensure that it too is initialized after the database has been initialized.



=== Flyway and Liquibase JDBC URLs
If you currently define a `spring.flyway.url` or `spring.liquibase.url` you may need to provide additional `username` and `password` properties.
In earlier versions of Spring Boot, these settings were derived from `spring.datasource` properties but this turned out to be problematic for people that provided their own DataSource beans.



=== Spring Data JPA
Spring Data JPA introduces a new `getById` method which replaces `getOne`.
If you find your application is now throwing a `LazyLoadingException` please rename any existing `getById` method to `getXyzById` (where `xyz` is an arbitrary string).
For more details, please read the https://docs.spring.io/spring-data/jpa/docs/2.6.0-RC1/reference/html/#new-features.2-5-0[updated Spring Data JPA reference documentation].



=== Spring Data Solr
Following its removal from Spring Data in 2021.0.0, auto-configuration for Spring Data Solr has been removed in this release.



=== Secure Info Endpoint
The `/info` actuator endpoint is no longer exposed over the web by default.
Additionally, if Spring Security is on the classpath and your application doesn't have a custom security configuration, the endpoint requires authenticated access by default.

Refer to the documentation on https://docs.spring.io/spring-boot/docs/2.5.0/reference/htmlsingle/#actuator.endpoints.exposing[exposing] and https://docs.spring.io/spring-boot/docs/2.5.0/reference/htmlsingle/#actuator.endpoints.security[securing] actuator endpoints to change these new defaults.



=== Task Scheduling Harmonization with Spring Integration
Spring Integration now reuses an available `TaskScheduler` rather that configuring its own.
In a typical application setup relying on the auto-configuration, this means that Spring Integration uses the auto-configured task scheduler that has a pool size of 1.
To restore Spring Integration's default of 10 threads, use the `spring.task.scheduling.pool.size` property.



=== Default Expression Language (EL) Implementation
The EL implementation that is included in Spring Boot's web and validation starters has changed. Tomcat's implementation (`org.apache.tomcat.embed.tomcat-embed-el`) is now used in place of the reference implementation from Glassfish (`org.glassfish:jakrta.el`).



=== Messages in the Default Error View
The `message` attribute in the default error view is now removed rather than blanked when it is not shown.
If you parse the error response JSON, you may need to deal with the missing item.

You can still use the `server.error.include-message` property if you want messages to be included.



=== Logging Shutdown Hooks
We now register a logging shutdown hook by default for jar based applications to ensure that logging resources are released when the JVM exits.
If your application is deployed as a war then the shutdown hook is not registered since the servlet container usually handles logging concerns.

Most applications will want the shutdown hook. However, if your application has complex context hierarchies, then you may need to disable it.
You can use the `logging.register-shutdown-hook` property to do that.



=== Gradle Default jar and war Tasks
The Spring Boot Gradle Plugin no longer automatically disables the standard Gradle `jar` and `war` tasks.
Instead we now apply a `classifier` to those tasks.

If you prefer to disable those tasks, the reference documentation {gradle-docs}/#packaging-executable-and-plain[includes updated examples].



=== Cassandra Throttling Properties
Spring Boot no longer provides default values for `spring.data.cassandra.request.throttler` properties.
If you rely on `max-queue-size`, `max-concurrent-requests`, `max-requests-per-second` or `drain-interval` you should set values that make sense for your application.



=== Customizing jOOQ's `DefaultConfiguration`
To streamline the customization of jOOQ's `DefaultConfiguration`, a bean that implements `DefaultConfigurationCustomizer` can now be defined. This customiser callback should be used in favour of defining one or more `*Provider` beans, the support for which has now been deprecated.



=== Groovy 3
The default version of Groovy has been upgraded to 3.x. If you are using Groovy and also using Spock, you should also upgrade to the latest Groovy 3.0-compatible release of Spock 2.0. Alternatively, use the `groovy.version` to downgrade back to Groovy 2.5.



=== Minimum Requirements Changes
Projects built with Gradle now require Gradle 6.8 or later.



=== Hibernate Validator 6.2
The default version of Hibernate Validate has been upgraded to 6.2.x. Hibernate Validator 6.2 changes how the expression language is used to interpolate constraint messages. Please see https://in.relation.to/2021/01/06/hibernate-validator-700-62-final-released/[this blog post from the Hibernate Validator team] for further details.



=== Deprecations from Spring Boot 2.3 and 2.4
Reflecting the Spring Boot https://github.com/spring-projects/spring-boot/wiki/Supported-Versions#release-compatibility[release compatibility policy], code deprecated in Spring Boot 2.3 has been removed in Spring Boot 2.5.
Code deprecated in Spring Boot 2.4 remains in place, and is scheduled for removal in Spring Boot 2.6.



== New and Noteworthy
TIP: Check link:Spring-Boot-2.5-Configuration-Changelog[the configuration changelog] for a complete overview of the changes in configuration.



=== Environment Variable Prefixes
It's now possible to specify a prefix for system environment variables so that you can run multiple different Spring Boot applications in the same environment.
Use `SpringApplication.setEnvironmentPrefix(...)` to set the prefix that you want to use when binding properties.

For example, the following will add a `myapp` prefix:

[source,java]
----
SpringApplication application = new SpringApplication(MyApp.class);
application.setEnvironmentPrefix("myapp");
application.run(args);
----

All properties will now expect a prefixed version.
For example, to change the server port you can set `MYAPP_SERVER_PORT`.



=== HTTP/2 over TCP (h2c)
All four embedded web containers now support HTTP/2 over TCP (h2c) without any manual customization. To enable h2c, set `server.http2.enabled` is `true` and leave `server.ssl.enabled` set to `false` (its default value).

As with the existing h2 support, depending on the embedded web server being used, the use of h2c may require additional dependencies. See {docs}/howto.html#howto.webserver.configure-http2[the reference documentation] for details.



=== Generic DataSource Initialization
A new generic mechanism is now available if you write code that initializes a DataSource.
This mechanism is also now used internally to setup correct bean dependencies for Flyway, Liquibase and Script based initialization.

Most developers won't need to directly make use of the new mechanism.
However, if you are developing a third-party starter for a data access library, you may want to provide a `DependsOnDataSourceInitializationDetector`.
See the {docs}/howto.html#howto-initialize-a-database-configuring-dependencies-initializer-detection[updated reference documentation] for details.



=== Database Initialization with R2DBC
Support for script-based initialization of an SQL database accessed via R2DBC has been added.
By default, scripts on the classpath named `schema.sql` and `data.sql` will be applied to the database automatically.
The initialization can be customized using the `spring.sql.init.*` configuration properties. Please
see the {docs}howto.html#howto-initialize-a-database-using-basic-scripts[reference documentation] for further details.



=== Liquibase DataSource
If you define a custom DataSource for use with Liquibase we now configure it using a `SimpleDriverDataSource`.
We previously used a pooling datasource which was unnecessary and inefficient for database initialization.




=== Layered WARs
The Spring Boot Maven and Gradle plugins now allow you to create layered WARs for use with Docker images.
Layered WARs work in a similar way to the Layered JAR support that was provided in earlier versions of Spring Boot.
Check out the {gradle-docs}#packaging-layered-archives[Gradle] and {maven-docs}#repackage-layers[Maven] reference documentation for more details.



=== Docker Image Building Support



==== Custom Buildpacks
The Maven and Gradle plugins both now support the use of custom Buildpacks.
You can set the `buildpacks` property to point at directories, tar.gz files, specific builder references or Docker images.

See the updated {gradle-docs}#packaging-oci-images[Gradle] and {maven-docs}#packaging-oci-images[Maven] reference documentation for more details.



==== Bindings
The Maven and Gradle plugins now both support volume bindings that can be passed to the buildpack builder.
These allow you to bind local paths or volumes for the buildpack to use.

See the updated {gradle-docs}#packaging-oci-images[Gradle] and {maven-docs}#packaging-oci-images[Maven] reference documentation for more details.



==== War Support
Both the Maven and Gradle plugin can now package executable war files into Docker images.
The existing `mvn spring-boot:image` or `./gradlew bootBuildImage` commands should be used if you want to create a Docker image for your war.



=== OpenMetrics for Prometheus
The `/actuator/prometheus` actuator endpoint can now provide both standard Prometheus as well as OpenMetrics responses.
The response returned will depend on the accept header that is provided with the HTTP request.



=== Metrics for Spring Data Repositories
Actuator will now generate Micrometer metrics for Spring Data repositories.
By default, metrics are named `spring.data.repository.invocations`.
To learn more, please see the {docs}actuator.html#actuator.metrics.supported.spring-data-repository[relevant section of the reference documentation].



=== @Timed Metrics with WebFlux
Aligning its capabilities with those of Spring MVC, `@Timed` can now be used to manually enable timing of requests handled by WebFlux controllers and functional handlers.
To use manual timing, set `management.metrics.web.server.request.autotime.enabled` to `false`.



=== MongoDB Metrics
When using Actuator, metrics for Mongo's connection pool and commands sent by the client are now generated automatically.
To learn more about MongoDB metrics, please see {docs}actuator.html#actuator.metrics.supported.mongodb[the relevant section of the reference documentation].



=== Actuator Endpoint for Quartz
A `/quartz` endpoint has been added to Actuator.
It provides detailed information about Quartz jobs and triggers.
Please see {actuator-api-docs}#quartz[the relevant section of the Actuator's API documentation] for further details.



=== `GET` requests to `actuator/startup`
The actuator's `startup` endpoint now supports `GET` requests.
Unlike a `POST` request, a `GET` request to the endpoint does not drain the event buffer and events will continue to be held in memory.



=== Abstract Routing DataSource Health
Actuator's health endpoint now shows the health of the targets of an `AbstractRoutingDataSource`.
Each target `DataSource` is named using its routing key.
As before, to ignore routing data sources in the health endpoint, set `management.health.db.ignore-routing-data-sources` to `true`.



=== Java 16 Support
This release provides support and is tested against Java 16.
Spring Boot 2.5 remains compatible with Java 8.



=== Gradle 7 Support
The Spring Boot Gradle plugin supports and is tested against Gradle 7.0.x.



=== Jetty 10 Support
Spring Boot 2.5 can now use Jetty 10 as an embedded web server.
As Jetty 10 requires Java 11, our default Jetty version will remain as 9.

To upgrade to Jetty 10, use the `jetty.version` property to override the version.
You should also exclude `org.eclipse.jetty.websocket:websocket-server` and `org.eclipse.jetty.websocket:javax-websocket-server-impl` from `spring-boot-starter-jetty` as they are Jetty 9-specific.



=== Documentation Updates
The HTML documentation published by the project has an updated look-and-feel and some new features.
You can now easily copy snippets of code to the clipboard by hovering over the sample and clicking the "copy" icon.
In addition, many of the samples now include full import statements that can be shown or hidden as required.

We also now have a "dark theme" switcher at the top of each document.



=== Miscellaneous
Apart from the changes listed above, there have also been lots of minor tweaks and improvements including:

- `management.endpoints.web.cors.allowed-origin-patterns` can now be used to configure the allowed origin patterns for Actuator endpoints https://github.com/spring-projects/spring-boot/pull/24608[(#24608)]
- `HttpSessionIdListener` beans are now automatically registered with the servlet context https://github.com/spring-projects/spring-boot/issues/24879[(#24879)]
- Couchbase now uses the auto-configured `ObjectMapper` by default https://github.com/spring-projects/spring-boot/issues/24616[(#24616)]
- Elasticsearch's `Sniffer` is now auto-configured when its `elasticsearch-rest-client-sniffer` module is on the classpath https://github.com/spring-projects/spring-boot/issues/24174[(#24174)]
- `spring.data.cassandra.controlconnection.timeout` can now be used to configure the timeout of Cassandra's control connection https://github.com/spring-projects/spring-boot/issues/24189[(#24189)]
- `spring.kafka.listener.only-log-record-metadata` can now be used to configure what's logged when retries are being attempted https://github.com/spring-projects/spring-boot/pull/24582[(#24582)]
- Support for Apache Phoenix, auto-detecting `jdbc:phoenix` JDBC URLs https://github.com/spring-projects/spring-boot/pull/24114[(#24114)]
- Configuration properties for Rabbit's key store and trust store algorithms https://github.com/spring-projects/spring-boot/pull/24076[(#24076)]
- The `/actuator` discovery page can now be disabled using the `management.endpoints.web.discovery.enabled` property.
- The `/actuator/configprops` and `actuator/env` endpoints now have `additional-keys-to-sanitize` properties that can be used to sanitize keys.
- You can now use a `EndpointObjectNameFactory` if you want to customize the name of JMX actuator endpoints.
- A new `DataSourceBuilder.derivedFrom(...)` method has been added that allows you to build a new `DataSource` that's derived from an existing one.
- When Spring Security is on the classpath, configuration properties can now be bound to `RSAPublicKey` and `RSAPrivateKey`.
- The RabbitMQ `ConnectionFactory` used by Spring AMQP can now be customized using a `ConnectionFactoryCustomizer` bean.
- Embedded database auto-configured can now be controlled using the new `spring.datasource.embedded-database-connection` configuration property. It can be set to any of the values of `EmbeddedDatabaseConnection`, including `none` to disable embedded database auto-configured entirely.
- `CloudPlatform` can now automatically detect Azure App Service.
- `server.tomcat.keep-alive-timeout` can be used to configure how long Tomcat will wait for another request before closing a keep-alive connection.
- `server.tomcat.max-keep-alive-requests` can be used to control the maximum number of requests that can be made on a keep-alive connection before it is closed.
- `spring.webflux.session.cookie.same-site` can be used to configure WebFlux's SameSite cookie policy. It is lax by default.
- Apache HttpClient 5 is now auto-configured for use with WebClient.
- A new `ApplicationEnvironment` class has been introduced which should improve a small performance boost.
- You can now configure Netty memory using the `spring.netty.leak-detection` property.



=== Dependency Upgrades
Spring Boot 2.5 moves to new versions of several Spring projects:

- https://spring.io/blog/2021/04/20/what-s-new-in-spring-data-2021-0[Spring Data 2021.0]
- https://docs.spring.io/spring-integration/docs/5.5.x/reference/html/whats-new.html#whats-new[Spring Integration 5.5]
- https://docs.spring.io/spring-security/site/docs/5.5.x/reference/html5/#new[Spring Security 5.5]
- Spring Session 2021.0
- Spring HATEOAS 1.3
- https://spring.io/blog/2021/04/14/spring-for-apache-kafka-2-7-0-available[Spring Kafka 2.7.0]

Numerous third-party dependencies have also been updated, some of the more noteworthy of which are the following:

- Kotlin 1.5
- Groovy 3.0
- Flyway 7.7
- Liquibase 4.3
- Jackson 2.12
- Kafka 2.7
- Cassandra Driver 4.10
- Embedded Mongo 3.0
- Hibernate Validator 6.2
- Jersey 2.33
- Mockito 3.7
- MongoDB 4.2
- JUnit Jupiter 5.7
- Elasticsearch 7.12



== Notable Deprecations in Spring Boot 2.5
The following notable deprecations have been made in Spring Boot 2.5

- `ActuatorMediaType` and `ApiVersion` in `org.springframework.boot.actuate.endpoint.http` in favor of equivalents in `org.springframework.boot.actuate.endpoint`
- Support for beans that implement jOOQ's `*Provider` callback interfaces or `Settings` has been deprecated.
A `DefaultConfigurationCustomizer` should be used instead.
- `EntityManagerFactoryDependsOnPostProcessor` in `org.springframework.boot.autoconfigure.data.jpa` has been relocated to `org.springframework.boot.autoconfigure.orm.jpa`
- `spring.artemis.host` and `spring.artemis.port` are deprecated. Please use `spring.artemis.broker-url` instead.
