An SQL database can be initialized in different ways depending on what your stack is. Of course, you can also do it manually, provided the database is a separate process. It is recommended to use a single mechanism for schema generation.
JPA has features for DDL generation, and these can be set up to run on startup against the database. This is controlled through two external properties:
spring.jpa.generate-ddl(boolean) switches the feature on and off and is vendor independent.spring.jpa.hibernate.ddl-auto(enum) is a Hibernate feature that controls the behavior in a more fine-grained way. This feature is described in more detail later in this guide.
You can set spring.jpa.hibernate.ddl-auto explicitly and the standard Hibernate property
values are none, validate, update, create, and create-drop. Spring Boot chooses
a default value for you based on whether it thinks your database is embedded. It defaults
to create-drop if no schema manager has been detected or none in all other cases. An
embedded database is detected by looking at the Connection type. hsqldb, h2, and
derby are embedded, and others are not. Be careful when switching from in-memory to a
‘real’ database that you do not make assumptions about the existence of the tables and
data in the new platform. You either have to set ddl-auto explicitly or use one of the
other mechanisms to initialize the database.
![[Note]](images/note.png) | Note |
|---|---|
You can output the schema creation by enabling the |
In addition, a file named import.sql in the root of the classpath is executed on
startup if Hibernate creates the schema from scratch (that is, if the ddl-auto property
is set to create or create-drop). This can be useful for demos and for testing if you
are careful but is probably not something you want to be on the classpath in production.
It is a Hibernate feature (and has nothing to do with Spring).
Spring Boot can automatically create the schema (DDL scripts) of your DataSource and
initialize it (DML scripts). It loads SQL from the standard root classpath locations:
schema.sql and data.sql, respectively. In addition, Spring Boot processes the
schema-${platform}.sql and data-${platform}.sql files (if present), where platform
is the value of spring.datasource.platform. This allows you to switch to
database-specific scripts if necessary. For example, you might choose to set it to the
vendor name of the database (hsqldb, h2, oracle, mysql, postgresql, and so on).
| Note |
|---|---|
Spring Boot automatically creates the schema of an embedded spring.datasource.initialization-mode=always |
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
|
If you use Spring Batch, it comes pre-packaged with SQL initialization scripts for most popular database platforms. Spring Boot can detect your database type and execute those scripts on startup. If you use an embedded database, this happens by default. You can also enable it for any database type, as shown in the following example:
spring.batch.initialize-schema=always
You can also switch off the initialization explicitly by setting
spring.batch.initialize-schema=never.
Spring Boot supports two higher-level migration tools: Flyway and Liquibase.
To automatically run Flyway database migrations on startup, add the
org.flywaydb:flyway-core to your classpath.
The migrations are scripts in the form V<VERSION>__<NAME>.sql (with <VERSION> an
underscore-separated version, such as ‘1’ or ‘2_1’). By default, they are in a folder
called classpath:db/migration, but you can modify that location by setting
spring.flyway.locations. This is a comma-separated list of one or more classpath:
or filesystem: locations. For example, the following configuration would search for
scripts in both the default classpath location and the /opt/migration directory:
spring.flyway.locations=classpath:db/migration,filesystem:/opt/migrationYou can also add a special {vendor} placeholder to use vendor-specific scripts. Assume
the following:
spring.flyway.locations=classpath:db/migration/\{vendor}Rather than using db/migration, the preceding configuration sets the folder to use
according to the type of the database (such as db/migration/mysql for MySQL). The list
of supported databases is available in
DatabaseDriver.
FlywayProperties
provides most of Flyway’s settings and a small set of additional properties that can be
used to disable the migrations or switch off the location checking. If you need more
control over the configuration, consider registering a FlywayConfigurationCustomizer
bean.
Spring Boot calls Flyway.migrate() to perform the database migration. If you would like
more control, provide a @Bean that implements
FlywayMigrationStrategy.
Flyway supports SQL and Java callbacks.
To use SQL-based callbacks, place the callback scripts in the classpath:db/migration
folder. To use Java-based callbacks, create one or more beans that implement
Callback. Any such beans are automatically registered with Flyway. They can be
ordered by using @Order or by implementing Ordered. Beans that implement the
deprecated FlywayCallback interface can also be detected, however they cannot be used
alongside Callback beans.
By default, Flyway autowires the (@Primary) DataSource in your context and
uses that for migrations. If you like to use a different DataSource, you can create
one and mark its @Bean as @FlywayDataSource. If you do so and want two data sources,
remember to create another one and mark it as @Primary. Alternatively, you can use
Flyway’s native DataSource by setting spring.flyway.[url,user,password]
in external properties. Setting either spring.flyway.url or spring.flyway.user
is sufficient to cause Flyway 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.
There is a Flyway sample so that you can see how to set things up.
You can also use Flyway to provide data for specific scenarios. For example, you can
place test-specific migrations in src/test/resources and they are run only when your
application starts for testing. Also, you can use profile-specific configuration to
customize spring.flyway.locations so that certain migrations run only when a particular
profile is active. For example, in application-dev.properties, you might specify the
following setting:
spring.flyway.locations=classpath:/db/migration,classpath:/dev/db/migrationWith that setup, migrations in dev/db/migration run only when the dev profile is
active.
To automatically run Liquibase database migrations on startup, add the
org.liquibase:liquibase-core to your classpath.
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.
By default, Liquibase autowires the (@Primary) DataSource in your context and uses
that for migrations. If you need to use a different DataSource, you can create one and
mark its @Bean as @LiquibaseDataSource. 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.
See
LiquibaseProperties
for details about available settings such as contexts, the default schema, and others.
There is a Liquibase sample so that you can see how to set things up.