Skip to content

Commit

Permalink
Enhance Database initialization how to guide
Browse files Browse the repository at this point in the history
  • Loading branch information
nikmanzotti authored and snicoll committed Apr 25, 2020
1 parent 092c321 commit f2b10be
Showing 1 changed file with 17 additions and 5 deletions.
22 changes: 17 additions & 5 deletions spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc
Expand Up @@ -1949,23 +1949,28 @@ 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:
[indent=0,subs="verbatim,quotes,attributes"]
----
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 <<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.
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]]
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down

0 comments on commit f2b10be

Please sign in to comment.