Hibernate's hbm2ddl Tool

Hi again,
The Hibernate hbm2ddl is a tool allows us to create, update, and validate a database schema using Hibernate mappings configuration. The .hbm files are Hibernate mapping files, but since the schema export/validation is done using the the internal configuration Hibernate creates for the entities mapping, we can use still use hbm2ddl when working with JPA. As usual in here I write about the JPA environment, just remember that the hbm2ddl can also be invoked from command line or using Ant task.

Setup
To invoke Hibernates hbm2ddl during the creation of the entity manager factory set the 'hibernate.hbm2ddl.auto' property to one of
·         create
·         create-drop
·         update
·         validate
Here is an example:
<persistence>
  <persistence-unit name="sampleContext" transaction-type="RESOURCE_LOCAL">
  <provider>org.hibernate.ejb.HibernatePersistence</provider>
  <properties>
    <property name="hibernate.connection.driver_class" value="org.apache.derby.jdbc.ClientDriver">
     <property name="hibernate.connection.username" value="app">
     <property name="hibernate.connection.password" value="app">
     <property name="hibernate.connection.url" value="jdbc:derby://localhost:1527/HibernateTestDB;create=true">
     <property name="hibernate.hbm2ddl.auto" value="validate">
   </properties>
   </persistence-unit>
</persistence>

The Options and Their Meanings

create

Hibernate will create the database when the entity manager factory is created (actually when Hibernate's SessionFactory is created by the entity manager factory). If a file named import.sql exists in the root of the class path ('/import.sql') Hibernate will execute the SQL statements read from the file after the creation of the database schema. It is important to remember that before Hibernate creates the schema it empties it (delete all tables, constraints, or any other database object that is going to be created in the process of building the schema).

create-drop

Same as 'create' but when the entity manager factory (which holds the SessionFactory) is explicitly closed the schema will be dropped.

update

Hibernate creates an update script trying to update the database structure to the current mapping. Does not read and invoke the SQL statements from import.sql. Useful, but we have to be careful, not all of the updates can be done performed ? for example adding a not null column to a table with existing data.

validate

Validates the existing schema with the current entities configuration. When using this mode Hibernate will not do any changes to the schema and will not use the import.sql file.

Mode
Reads
import.sql
Alters Database
Structure
Comments
update
No
Yes

create
Yes
Yes
Empties the database before creating it
create-drop
Yes
Yes
Drops the database when the SessionFactory is closed
validate
No
No

Comments

landrain said…
I was surprised because this rather important subject is not covered in the official hibernate documentation. So, thanks for the explanation.
Mayank said…
Thanks Eyal, Its very easy to understand concepts when explained with such a simplicity.
rags said…
good post
keep them coming.ty
Anonymous said…
great, lucid explanation! Thanks for this... as usual the official docs leave these important facts out... took me half a day to figure out why my table data was being overwritten! ..

thanks again.
Unknown said…
Is there a way to export the DDL generated when using hbm2ddl in your persistence.xml?
Eyal Lupu said…
Hi Steve,
There might be a way to export the DDL commands but I am not familiar with any.

Eyal
Anonymous said…
Can I say import a schema say from an RDBMS like Oracle into HSQL DB?? If yes how would I do it???

Thanks,
Gurudutta
Does anyone know which is the default value? We have this config item commented-out in the config and the docs are remarkably silent at that...
Eyal Lupu said…
Hi,
The default value is just not to do anything - just to leave the schema as is.

Eyal
Anonymous said…
Thanks a lot.

It is still the only valuable information of hbm2ddl.auto after 4 years.

Stathis Alexopoulos
kp said…
I tried the 'update' mode for changes in the column datatype and column drop, But it won't work. It only creates new column but not drop.
How do we go about dropping the column with hbm2ddl tool?
Anonymous said…
"The default value is just not to do anything - just to leave the schema as is."

Boy, that is NOT the behavior I'm seeing. Not only is it still replacing my schema, it's replacing it with an OLD schema. Grrr.

Thanks for this post.
Jeevan said…
property name="hibernate.hbm2ddl.auto" value="validate"

Worked for me.
I got a Hibernate Exception, showing …. “Wrong column type in . for column Created_by_User_ID. Found: bigint, expected: int”

A couple of questions:
1. Where does the “import.sql”, exist or gets created?

2. Is there a way to get a report of all the inconsistencies that exist as Unit test execution stops when it hits the first problem;
I have to correct it, execute UT again to get the next inconsistency.

Would prefer to get a full report, instead.

TIA !!

~g1
Anonymous said…
Thank you very much.
grails cookbook said…
i encountered a company before that writes their own SQL to create tables. Then they write their POJOs afterwards to match their tables. But in the end, they let Hibernate create the tables when run outside development environment. True story
Flemming said…
You missed 'none' which can be used to ensure that Hibernate does not do anything to your schema upon start - not even validate it.
Anonymous said…
I didn't see any role of import.sql

Popular posts from this blog

New in Spring MVC 3.1: CSRF Protection using RequestDataValueProcessor

Hibernate Exception - Simultaneously Fetch Multiple Bags

Hibernate Derived Properties - Performance and Portability