Skip to content

Commit 5ed27dd

Browse files
committed
Merge pull request #21077 from nikmanzotti
* pr/21077: Polish "Enhance Database initialization how to guide" Enhance Database initialization how to guide Closes gh-21077
2 parents 092c321 + 8041099 commit 5ed27dd

File tree

1 file changed

+21
-5
lines changed
  • spring-boot-project/spring-boot-docs/src/main/asciidoc

1 file changed

+21
-5
lines changed

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1949,23 +1949,32 @@ For example, you might choose to set it to the vendor name of the database (`hsq
19491949

19501950
[NOTE]
19511951
====
1952-
Spring Boot automatically creates the schema of an embedded `DataSource`.
1952+
When only basic SQL scripts are used, Spring Boot automatically creates the schema of an embedded `DataSource`.
19531953
This behavior can be customized by using the configprop:spring.datasource.initialization-mode[] property.
19541954
For instance, if you want to always initialize the `DataSource` regardless of its type:
19551955
19561956
[indent=0,subs="verbatim,quotes,attributes"]
19571957
----
19581958
spring.datasource.initialization-mode=always
19591959
----
1960+
1961+
In a JPA-based app, you can choose to let Hibernate create the schema or use `schema.sql`, but you cannot do both.
1962+
Make sure to disable `spring.jpa.hibernate.ddl-auto` if you use `schema.sql`.
1963+
1964+
[indent=0,subs="verbatim,quotes,attributes"]
1965+
----
1966+
spring.jpa.hibernate.ddl-auto=none
1967+
----
1968+
1969+
If you are using a <<spring-boot-features.adoc#howto-use-a-higher-level-database-migration-tool,Higher-level Database Migration Tool>>, like Flyway or Liquibase, you cannot use basic SQL scripts to create and initialize the schema.
1970+
In this situation, if `schema.sql` and `data.sql` are present, they will be ignored.
1971+
It is not possible to use a Database Migration Tool to manage schema creation, and a basic SQL script to initialize it.
19601972
====
19611973

19621974
By default, Spring Boot enables the fail-fast feature of the Spring JDBC initializer.
19631975
This means that, if the scripts cause exceptions, the application fails to start.
19641976
You can tune that behavior by setting `spring.datasource.continue-on-error`.
19651977

1966-
NOTE: In a JPA-based app, you can choose to let Hibernate create the schema or use `schema.sql`, but you cannot do both.
1967-
Make sure to disable `spring.jpa.hibernate.ddl-auto` if you use `schema.sql`.
1968-
19691978

19701979

19711980
[[howto-initialize-a-spring-batch-database]]
@@ -2056,6 +2065,13 @@ With that setup, migrations in `dev/db/migration` run only when the `dev` profil
20562065
==== Execute Liquibase Database Migrations on Startup
20572066
To automatically run Liquibase database migrations on startup, add the `org.liquibase:liquibase-core` to your classpath.
20582067

2068+
[NOTE]
2069+
====
2070+
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.
2071+
This behavior can be customized by using the configprop:spring.liquibase.enabled[] property, setting different values in the `main` and `test` configurations.
2072+
It is not possible to use two different ways to initialize the database (e.g. Liquibase for application startup, JPA for test runs).
2073+
====
2074+
20592075
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`.
20602076
In addition to YAML, Liquibase also supports JSON, XML, and SQL change log formats.
20612077

@@ -2064,7 +2080,7 @@ If you need to use a different `DataSource`, you can create one and mark its `@B
20642080
If you do so and you want two data sources, remember to create another one and mark it as `@Primary`.
20652081
Alternatively, you can use Liquibase's native `DataSource` by setting `spring.liquibase.[url,user,password]` in external properties.
20662082
Setting either `spring.liquibase.url` or `spring.liquibase.user` is sufficient to cause Liquibase to use its own `DataSource`.
2067-
If any of the three properties has not be set, the value of its equivalent `spring.datasource` property will be used.
2083+
If any of the three properties has not been set, the value of its equivalent `spring.datasource` property will be used.
20682084

20692085
See {spring-boot-autoconfigure-module-code}/liquibase/LiquibaseProperties.java[`LiquibaseProperties`] for details about available settings such as contexts, the default schema, and others.
20702086

0 commit comments

Comments
 (0)