diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc index e309684600..9d31100eaa 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc @@ -1946,7 +1946,7 @@ For example, you might choose to set it to the vendor name of the database (`hsq [NOTE] ==== -Spring Boot automatically creates the schema of an embedded `DataSource`. +When only basic SQL scripts are used, Spring Boot automatically creates the schema of an embedded `DataSource`. This behavior can be customized by using the configprop:spring.datasource.initialization-mode[] property. For instance, if you want to always initialize the `DataSource` regardless of its type: @@ -1954,15 +1954,24 @@ For instance, if you want to always initialize the `DataSource` regardless of it ---- spring.datasource.initialization-mode=always ---- + +In a JPA-based app, you can choose to let Hibernate create the schema or use `schema.sql`, but you cannot do both. +Make sure to disable `spring.jpa.hibernate.ddl-auto` if you use `schema.sql`. + +[indent=0,subs="verbatim,quotes,attributes"] +---- + spring.jpa.hibernate.ddl-auto=none +---- + +If you are using a <>, like Flyway or Liquibase, you cannot use basic SQL scripts to create and initialize the schema. +In this situation, if `schema.sql` and `data.sql` are present, they will be ignored. +It is not possible to use a Database Migration Tool to manage schema creation, and a basic SQL script to initialize it. ==== By default, Spring Boot enables the fail-fast feature of the Spring JDBC initializer. This means that, if the scripts cause exceptions, the application fails to start. You can tune that behavior by setting `spring.datasource.continue-on-error`. -NOTE: In a JPA-based app, you can choose to let Hibernate create the schema or use `schema.sql`, but you cannot do both. -Make sure to disable `spring.jpa.hibernate.ddl-auto` if you use `schema.sql`. - [[howto-initialize-a-database-using-r2dbc]] @@ -2071,6 +2080,13 @@ With that setup, migrations in `dev/db/migration` run only when the `dev` profil ==== Execute Liquibase Database Migrations on Startup To automatically run Liquibase database migrations on startup, add the `org.liquibase:liquibase-core` to your classpath. +[NOTE] +==== +When you add the `org.liquibase:liquibase-core` to your classpath, database migrations run by default for both during application startup and before your tests run. +This behavior can be customized by using the configprop:spring.liquibase.enabled[] property, setting different values in the `main` and `test` configurations. +It is not possible to use two different ways to initialize the database (e.g. Liquibase for application startup, JPA for test runs). +==== + By default, the master change log is read from `db/changelog/db.changelog-master.yaml`, but you can change the location by setting `spring.liquibase.change-log`. In addition to YAML, Liquibase also supports JSON, XML, and SQL change log formats. @@ -2079,7 +2095,7 @@ If you need to use a different `DataSource`, you can create one and mark its `@B If you do so and you want two data sources, remember to create another one and mark it as `@Primary`. Alternatively, you can use Liquibase's native `DataSource` by setting `spring.liquibase.[url,user,password]` in external properties. Setting either `spring.liquibase.url` or `spring.liquibase.user` is sufficient to cause Liquibase to use its own `DataSource`. -If any of the three properties has not be set, the value of its equivalent `spring.datasource` property will be used. +If any of the three properties has not been set, the value of its equivalent `spring.datasource` property will be used. See {spring-boot-autoconfigure-module-code}/liquibase/LiquibaseProperties.java[`LiquibaseProperties`] for details about available settings such as contexts, the default schema, and others.