Toolset Guide
Roundtrip engineering with Hibernate is possible using a set of Eclipse plugins,
commandline tools, as well as Ant tasks.
The Hibernate Tools currently include plugins for the Eclipse
IDE as well as Ant tasks for reverse engineering of existing databases:
Mapping Editor: An editor for Hibernate XML mapping files,
supporting auto-completion and syntax highlighting. It also supports semantic
auto-completion for class names and property/field names, making it much more versatile than a normal XML editor.
Console: The console is a new view in Eclipse. In addition to
a tree overview of your console configurations, you also get an interactive view
of your persistent classes and their relationships. The console allows you to
execute HQL queries against your database and browse the result directly in
Eclipse.
Development Wizards: Several wizards are provided with the
Hibernate Eclipse tools; you can use a wizard to quickly generate Hibernate configuration
(cfg.xml) files, or you may even completely reverse engineer an existing database schema
into POJO source files and Hibernate mapping files. The reverse engineering wizard
supports customizable templates.
Ant Tasks:
Please refer to the Hibernate Tools package and it's documentation
for more information.
However, the Hibernate main package comes bundled with an integrated tool (it can even
be used from "inside" Hibernate on-the-fly): SchemaExport aka
hbm2ddl.
Automatic schema generation
DDL may be generated from your mapping files by a Hibernate utility. The generated
schema includes referential integrity constraints (primary and foreign keys) for
entity and collection tables. Tables and sequences are also created for mapped
identifier generators.
You must specify a SQL Dialect via the
hibernate.dialect property when using this tool, as DDL
is highly vendor specific.
First, customize your mapping files to improve the generated schema.
Customizing the schema
Many Hibernate mapping elements define optional attributes named length,
precision and scale. You may set the length, precision
and scale of a column with this attribute.
]]>
]]>
Some tags also accept a not-null attribute (for generating a
NOT NULL constraint on table columns) and a unique
attribute (for generating UNIQUE constraint on table columns).
]]>
]]>
A unique-key attribute may be used to group columns in
a single unique key constraint. Currently, the specified value of the
unique-key attribute is not used
to name the constraint in the generated DDL, only to group the columns in
the mapping file.
]]>
An index attribute specifies the name of an index that
will be created using the mapped column or columns. Multiple columns may be
grouped into the same index, simply by specifying the same index name.
]]>
A foreign-key attribute may be used to override the name
of any generated foreign key constraint.
]]>
Many mapping elements also accept a child <column> element.
This is particularly useful for mapping multi-column types:
]]>
The default attribute lets you specify a default value for
a column (you should assign the same value to the mapped property before
saving a new instance of the mapped class).
]]>
]]>
The sql-type attribute allows the user to override the default
mapping of a Hibernate type to SQL datatype.
]]>
The check attribute allows you to specify a check constraint.
]]>
...
]]>
Summary
Attribute
Values
Interpretation
length
number
column length
precision
number
column decimal precision
scale
number
column decimal scale
not-null
true|false
specfies that the column should be non-nullable
unique
true|false
specifies that the column should have a unique constraint
index
index_name
specifies the name of a (multi-column) index
unique-key
unique_key_name
specifies the name of a multi-column unique constraint
foreign-key
foreign_key_name
specifies the name of the foreign key constraint generated
for an association, for a <one-to-one>,
<many-to-one>, <key>,
or <many-to-many> mapping element. Note that
inverse="true" sides will not be considered
by SchemaExport.
sql-type
SQL column type
overrides the default column type (attribute of
<column> element only)
default
SQL expression
specify a default value for the column
check
SQL expression
create an SQL check constraint on either column or table
The <comment> element allows you to specify comments
for the generated schema.
Current customers only
...
]]>
Balance in USD
]]>
This results in a comment on table or
comment on column statement in the generated
DDL (where supported).
Running the tool
The SchemaExport tool writes a DDL script to standard out and/or
executes the DDL statements.
java -cp hibernate_classpaths
org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files
SchemaExport Command Line Options
Option
Description
--quiet
don't output the script to stdout
--drop
only drop the tables
--create
only create the tables
--text
don't export to the database
--output=my_schema.ddl
output the ddl script to a file
--naming=eg.MyNamingStrategy
select a NamingStrategy
--config=hibernate.cfg.xml
read Hibernate configuration from an XML file
--properties=hibernate.properties
read database properties from a file
--format
format the generated SQL nicely in the script
--delimiter=;
set an end of line delimiter for the script
You may even embed SchemaExport in your application:
Properties
Database properties may be specified
as system properties with -D<property>
in hibernate.properties
in a named properties file with --properties
The needed properties are:
SchemaExport Connection Properties
Property Name
Description
hibernate.connection.driver_class
jdbc driver class
hibernate.connection.url
jdbc url
hibernate.connection.username
database user
hibernate.connection.password
user password
hibernate.dialect
dialect
Using Ant
You can call SchemaExport from your Ant build script:
]]>
Incremental schema updates
The SchemaUpdate tool will update an existing schema with "incremental" changes.
Note that SchemaUpdate depends heavily upon the JDBC metadata API, so it will
not work with all JDBC drivers.
java -cp hibernate_classpaths
org.hibernate.tool.hbm2ddl.SchemaUpdate options mapping_files
SchemaUpdate Command Line Options
Option
Description
--quiet
don't output the script to stdout
--text
don't export the script to the database
--naming=eg.MyNamingStrategy
select a NamingStrategy
--properties=hibernate.properties
read database properties from a file
--config=hibernate.cfg.xml
specify a .cfg.xml file
You may embed SchemaUpdate in your application:
Using Ant for incremental schema updates
You can call SchemaUpdate from the Ant script:
]]>
Schema validation
The SchemaValidator tool will validate that the existing database schema "matches"
your mapping documents. Note that SchemaValidator depends heavily upon the JDBC
metadata API, so it will not work with all JDBC drivers. This tool is extremely useful for testing.
java -cp hibernate_classpaths
org.hibernate.tool.hbm2ddl.SchemaValidator options mapping_files
SchemaValidator Command Line Options
Option
Description
--naming=eg.MyNamingStrategy
select a NamingStrategy
--properties=hibernate.properties
read database properties from a file
--config=hibernate.cfg.xml
specify a .cfg.xml file
You may embed SchemaValidator in your application:
Using Ant for schema validation
You can call SchemaValidator from the Ant script:
]]>