Introduction

In this article, we are going to see how the Hibernate hbm2ddl.auto schema generation tool works, and when it’s appropriate to use it.

Hibernate schema generation strategies

When working with JPA and Hibernate, you have two options to manage the underlying database schema:

• You can encapsulate schema changes in migration scripts and use a tool, like Flyway, to apply the migration scripts upon starting the application.
• You can generate or update the database schema from the JPA and Hibernate entity mappings using the hbm2ddl.auto tool.

While the former option is the best strategy when it comes to applying the database schema migrations, the latter strategy can also be useful for some very specific use cases.

For instance, the Hibernate Core integration tests make heavy use of the hbm2ddl.auto tool to manage the underlying database schema. Since integration tests must run in isolation, each integration test defines its own set of JPA and Hibernate entities, which, in turn, are mapped to a database schema.

To avoid creating database scripts for all supported relational databases, and considering that are over 10k integration tests, the hbm2ddl.auto tool allows the Hibernate project to generate the DDL scripts automatically. This is extremely convenient for the Hibernate development team as it allows them to focus on the test functionality.

Hibernate hbm2ddl.auto schema generation options

The hibernate.hbm2ddl.auto configuration property is used to customize the Hibernate database schema generation process, and it can take the following values:

• none – This option disables the hbm2ddl.auto tool, so Hibernate is not going to take any action for managing the underlying database schema.
• create-only – This option instructs Hibernate to generate the database schema from the entity model.
• drop – This option instructs Hibernate to drop the database schema using the entity model as a reference for the DDL DROP statements.
• create – This option instructs Hibernate to drop the database schema and recreate it afterward using the entity model as a reference.
• create-drop – This option instructs Hibernate to drop the database schema and recreate it afterward using the entity model as a reference. And, upon closing the JPA EntityManagerFactory or the Hibernate SessionFactory, the database schema will be dropped again.
• validate – This option instructs Hibernate to validate the underlying database schema against the entity mappings.
• update – This option instructs Hibernate to update the database schema by comparing the existing schema with the entity mappings and generate the appropriate schema migration scripts.

Which Hibernate hbm2ddl.auto options to use?

If you want to create the schema migration scripts manually, then you should not set the hibernate.hbm2ddl.auto configuration property since none is the default schema generation strategy.

If you are using a schema migration tool, like Flyway, and want to generate the initial migration script from the JPA and Hibernate entities, then you should use the create-only and drop options and log the auto-generated SQL statements in order to extract the DDL statements.

The create and create-drop options make sense for the Hibernate Core integration tests but are not suitable for an end-user project because you should use the same schema migration scripts you are using for the production system in order to generate the database schema needed for running the integration tests.

The update option is to be avoided as you are better off handling the schema migrations with a tool like Flyway.

The validate option could be useful when running integration tests to make sure that the underlying schema is compatible with the JPA entity mappings. However, if you have integration tests covering all read and write data access paths, then you shouldn’t need the validate option at all.

The JPA schema generation options

The Hibernate-specific hibernate.hbm2ddl.auto configuration has been standardized by JPA via the following two settings:

• javax.persistence.schema-generation.database.action
• javax.persistence.schema-generation.scripts.action

The javax.persistence.schema-generation.database.action configuration tells Hibernate whether to apply the schema migration against the underlying database upon bootstrapping the EntityManagerFactory.

The javax.persistence.schema-generation.scripts.action configuration tells Hibernate whether to generate the schema migration DDL statements to an external file. The CREATE DDL statements are written to the file given by the javax.persistence.schema-generation.scripts.create-target configuration property while the DROP DDL statements are written to the file given by the javax.persistence.schema-generation.scripts.drop-target configuration property.

The JPA javax.persistence.schema-generation.database.action and javax.persistence.schema-generation.scripts.action configuration property ca take the following values:

• none – This is the default option, and it disables the schema generation tool.
• create – This option instructs Hibernate to generate the database schema from the entity model. It’s equivalent to the create-only hibernate.hbm2ddl.auto strategy.
• drop – This option is equivalent to the drop hibernate.hbm2ddl.auto strategy.
• drop-and-create – This option instructs Hibernate to drop the database schema and recreate it afterward using the entity model as a reference. It’s equivalent to the create hibernate.hbm2ddl.auto strategy.

As you can see, there’s no JPA equivalent for the create-drop, validate, and update hibernate.hbm2ddl.auto strategies.

I'm running an online workshop on the 20-21 and 23-24 of November about High-Performance Java Persistence.

If you enjoyed this article, I bet you are going to love my Book and Video Courses as well.

Conclusion

First of all, the hbm2ddl.auto schema generation tool is very useful for the Hibernate project because it allows creating integration tests that can run on any of the supported relation database systems.

Although your project should use a tool like Flyway to manage the schema migration scripts, you can still use hbm2ddl.auto to generate either the initial script or even migration scripts, with the observation that you should manually review them and maybe enhance according to your application requirements.

Insert details about how the information is going to be processed

DOWNLOAD NOW