Hibernate.orgCommunity Documentation

Chapter 1. Database access

Table of Contents

1.1. Connecting
1.1.1. Configuration
1.1.2. Obtaining a JDBC connection
1.2. Connection pooling
1.2.1. c3p0 connection pool
1.2.2. Proxool connection pool
1.2.3. Obtaining connections from an application server, using JNDI
1.2.4. Other connection-specific configuration
1.2.5. Optional configuration properties
1.3. Dialects
1.3.1. Specifying the Dialect to use
1.3.2. Dialect resolution
1.4. Automatic schema generation with SchemaExport
1.4.1. Customizing the mapping files
1.4.2. Running the SchemaExport tool

Hibernate connects to databases on behalf of your application. It can connect through a variety of mechanisms, including:

  • Stand-alone built-in connection pool

  • javax.sql.DataSource

  • Connection pools, including support for two different third-party opensource JDBC connection pools:

    • c3p0

    • proxool

  • Application-supplied JDBC connections. This is not a recommended approach and exists for legacy reasons


The built-in connection pool is not intended for production environments.

Hibernate obtains JDBC connections as needed though the org.hibernate.service.jdbc.connections.spi.ConnectionProvider interface which is a service contract. Applications may also supply their own org.hibernate.service.jdbc.connections.spi.ConnectionProvider implementation to define a custom approach for supplying connections to Hibernate (from a different connection pool implementation, for example).

You can configure database connections using a properties file, an XML deployment descriptor or programmatically.

Example 1.2. hibernate.cfg.xml for a connection to the bundled HSQL database

<?xml version='1.0' encoding='utf-8'?>

        xsi:schemaLocation="http://www.hibernate.org/xsd/hibernate-configuration hibernate-configuration-4.0.xsd"
    <!-- Database connection settings -->
    <property name="connection.driver_class">org.hsqldb.jdbcDriver</property>
    <property name="connection.url">jdbc:hsqldb:hsql://localhost</property>
    <property name="connection.username">sa</property>
    <property name="connection.password"></property>

    <!-- JDBC connection pool (use the built-in) -->
    <property name="connection.pool_size">1</property>

    <!-- SQL dialect -->
    <property name="dialect">org.hibernate.dialect.HSQLDialect</property>

    <!-- Enable Hibernate's automatic session context management -->
    <property name="current_session_context_class">thread</property>

    <!-- Disable the second-level cache  -->
    <property name="cache.provider_class">org.hibernate.cache.internal.NoCacheProvider</property>

    <!-- Echo all executed SQL to stdout -->
    <property name="show_sql">true</property>

    <!-- Drop and re-create the database schema on startup -->
    <property name="hbm2ddl.auto">update</property>
    <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>

An instance of object org.hibernate.cfg.Configuration represents an entire set of mappings of an application's Java types to an SQL database. The org.hibernate.cfg.Configuration builds an immutable org.hibernate.SessionFactory, and compiles the mappings from various XML mapping files. You can specify the mapping files directly, or Hibernate can find them for you.

Other ways to configure Hibernate programmatically

  • Pass an instance of java.util.Properties to Configuration.setProperties().

  • Set System properties using java -Dproperty=value

Hibernate's internal connection pooling algorithm is rudimentary, and is provided for development and testing purposes. Use a third-party pool for best performance and stability. To use a third-party pool, replace the hibernate.connection.pool_size property with settings specific to your connection pool of choice. This disables Hibernate's internal connection pool.

Although SQL is relatively standardized, each database vendor uses a subset of supported syntax. This is referred to as a dialect. Hibernate handles variations across these dialects through its org.hibernate.dialect.Dialect class and the various subclasses for each vendor dialect.

SchemaExport is a Hibernate utility which generates DDL from your mapping files. The generated schema includes referential integrity constraints, primary and foreign keys, for entity and collection tables. It also creates tables and sequences for mapped identifier generators.

Before Hibernate can generate your schema, you must customize your mapping files.

Hibernate provides several elements and attributes to customize your mapping files. They are listed in Table 1.3, “Elements and attributes provided for customizing mapping files”, and a logical order of customization is presented in Procedure 1.1, “Customizing the schema”.

Procedure 1.1. Customizing the schema

  1. Set the length, precision, and scale of mapping elements.

    Many Hibernate mapping elements define optional attributes named length, precision, and scale.

    <property name="zip" length="5"/>
    <property name="balance" precision="12" scale="2"/>
  2. Set the not-null, UNIQUE, unique-key attributes.

    The not-null and UNIQUE attributes generate constraints on table columns.

    The unique-key attribute groups columns in a single, unique key constraint. Currently, the specified value of the unique-key attribute does not name the constraint in the generated DDL. It only groups the columns in the mapping file.

    <many-to-one name="bar" column="barId" not-null="true"/>
    <element column="serialNumber" type="long" not-null="true" unique="true"/>

    <many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
    <property name="employeeId" unique-key="OrgEmployee"/>
  3. Set the index and foreign-key attributes.

    The index attribute specifies the name of an index for Hibernate to create using the mapped column or columns. You can group multiple columns into the same index by assigning them the same index name.

    A foreign-key attribute overrides the name of any generated foreign key constraint.

    <many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>
  4. Set child <column> elements.

    Many mapping elements accept one or more child <column> elements. This is particularly useful for mapping types involving multiple columns.

    <property name="name" type="my.customtypes.Name"/>
        <column name="last" not-null="true" index="bar_idx" length="30"/>
        <column name="first" not-null="true" index="bar_idx" length="20"/>
        <column name="initial"/>
  5. Set the default attribute.

    The default attribute represents a default value for a column. Assign the same value to the mapped property before saving a new instance of the mapped class.

    <property name="credits" type="integer" insert="false">
        <column name="credits" default="10"/>
    <version name="version" type="integer" insert="false">
        <column name="version" default="0"/>
  6. Set the sql-type attribure.

    Use the sql-type attribute to override the default mapping of a Hibernate type to SQL datatype.

    <property name="balance" type="float">
        <column name="balance" sql-type="decimal(13,3)"/>
  7. Set the check attribute.

    use the check attribute to specify a check constraint.

    <property name="foo" type="integer">
      <column name="foo" check="foo > 10"/>
    <class name="Foo" table="foos" check="bar < 100.0">
      <property name="bar" type="float"/>
  8. Add <comment> elements to your schema.

    Use the <comment> element to specify comments for the generated schema.

    <class name="Customer" table="CurCust">
      <comment>Current customers only</comment>