Hibernate hbm2ddl.auto schema generation
Imagine having a tool that can automatically detect JPA and Hibernate performance issues. Wouldn’t that be just awesome?
Well, Hypersistence Optimizer is that tool! And it works with Spring Boot, Spring Framework, Jakarta EE, Java EE, Quarkus, or Play Framework.
So, enjoy spending your time on the things you love rather than fixing performance issues in your production system on a Saturday night!
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
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.autotool, 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
EntityManagerFactoryor 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
drop options and log the auto-generated SQL statements in order to extract the DDL statements.
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.
update option is to be avoided as you are better off handling the schema migrations with a tool like Flyway.
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
hibernate.hbm2ddl.auto configuration has been standardized by JPA via the following two settings:
javax.persistence.schema-generation.database.action configuration tells Hibernate whether to apply the schema migration against the underlying database upon bootstrapping 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.
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
drop– This option is equivalent to the
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
As you can see, there’s no JPA equivalent for the
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.