hibernate.hbm2ddl.auto

 

Hibernate's hbm2ddl tool

This entry also appears in my new blog at http://blog.eyallupu.com. A direct link to the entry ishere.

Hi again,

I was asked by one of my customers about the hbm2ddl, and I since I had some time to spare I decided to write the answer in the blog, here it is:

Hibernate hbm2ddl is a tool allowing 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:

<?xml version="1.0" encoding="UTF-8"?>

<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 itempties 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 theschema will be dropped.

update

Hibernate creates an update script trying to update the database structure to the current mapping. Doesnot 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 willnot 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

 

 

hibernate.cfg.xml 中hibernate.hbm2ddl.auto配置节点如下：
<properties>
<property name="hibernate.show_sql" value="true" />     
<property name="hibernate.hbm2ddl.auto" value="create" />
</properties>

Hibernate Reference Documentation 3.3.1解释如下：
Automatically validate or export schema DDL to the database when the SessionFactory is created.
With create-drop, the database schema will be dropped when the SessionFactory is closed explicitly.
eg. validate | update | create | create-drop

 

其实这个hibernate.hbm2ddl.auto参数的作用主要用于：自动创建|更新|验证数据库表结构。如果不是此方面的需求建议set value="none"。
create：
每次加载hibernate时都会删除上一次的生成的表，然后根据你的model类再重新来生成新表，哪怕两次没有任何改变也要这样执行，这就是导致数据库表数据丢失的一个重要原因。
create-drop ：
每次加载hibernate时根据model类生成表，但是sessionFactory一关闭,表就自动删除。
update：
最常用的属性，第一次加载hibernate时根据model类会自动建立起表的结构（前提是先建立好数据库），以后加载hibernate时根据 model类自动更新表结构，即使表结构改变了但表中的行仍然存在不会删除以前的行。要注意的是当部署到服务器后，表结构是不会被马上建立起来的，是要等应用第一次运行起来后才会。
validate ：
每次加载hibernate时，验证创建数据库表结构，只会和数据库中的表进行比较，不会创建新表，但是会插入新值。

再说点“废话”：
当我们把hibernate.hbm2ddl.auto=create时hibernate先用hbm2ddl来生成数据库schema。
当我们把hibernate.cfg.xml文件中hbm2ddl属性注释掉，这样我们就取消了在启动时用hbm2ddl来生成数据库schema。通常只有在不断重复进行单元测试的时候才需要打开它，但再次运行hbm2ddl会把你保存的一切都删除掉（drop）---- create配置的含义是：“在创建SessionFactory的时候，从scema中drop掉所以的表，再重新创建它们”。
注意，很多Hibernate新手在这一步会失败，我们不时看到关于Table not found错误信息的提问。但是，只要你根据上面描述的步骤来执行，就不会有这个问题，因为hbm2ddl会在第一次运行的时候创建数据库schema，后续的应用程序重启后还能继续使用这个schema。假若你修改了映射，或者修改了数据库schema,你必须把hbm2ddl重新打开一次。