From f2b10be01e740bb95e40b670945cca96d1573247 Mon Sep 17 00:00:00 2001 From: nikmanzotti <34871840+nikmanzotti@users.noreply.github.com> Date: Wed, 22 Apr 2020 15:37:30 +0200 Subject: [PATCH] Enhance Database initialization how to guide See gh-21077 --- .../src/main/asciidoc/howto.adoc | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index cf876d4c14c0..2e9a42c95b5b 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -1949,7 +1949,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: @@ -1957,15 +1957,20 @@ 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-spring-batch-database]] @@ -2056,6 +2061,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, by default database migrations will run 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` folders. +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. @@ -2064,7 +2076,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.