Hibernate's hbm2ddl Tool

>> Tuesday, May 29, 2007

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

17 comments:

nidget July 19, 2010 at 5:24 AM  

I was surprised because this rather important subject is not covered in the official hibernate documentation. So, thanks for the explanation.

Mayank July 24, 2010 at 12:16 AM  

Thanks Eyal, Its very easy to understand concepts when explained with such a simplicity.

rags July 31, 2010 at 2:23 AM  

good post
keep them coming.ty

Anonymous September 29, 2010 at 4:00 AM  

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.

Steve October 8, 2010 at 2:53 PM  

Is there a way to export the DDL generated when using hbm2ddl in your persistence.xml?

Eyal Lupu October 10, 2010 at 10:36 PM  

Hi Steve,
There might be a way to export the DDL commands but I am not familiar with any.

Eyal

Anonymous November 11, 2010 at 12:47 AM  

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

Thanks,
Gurudutta

Anton S. Kraievoy July 22, 2011 at 1:39 AM  

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 July 23, 2011 at 1:07 AM  

Hi,
The default value is just not to do anything - just to leave the schema as is.

Eyal

Anonymous August 21, 2011 at 12:39 AM  

Thanks a lot.

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

Stathis Alexopoulos

kp September 14, 2011 at 4:06 AM  

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 April 5, 2012 at 1:17 AM  

"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 August 30, 2012 at 7:34 AM  

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 May 2, 2013 at 2:49 PM  

Thank you very much.

grails cookbook July 20, 2013 at 9:09 AM  

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 September 13, 2013 at 1:55 AM  

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 December 10, 2013 at 5:44 AM  

I didn't see any role of import.sql

  © Blogger templates Sunset by Ourblogtemplates.com 2008

Back to TOP