<< 3Quick Start Guide
(Quick Reference)
5Domain Modelling in GORM >>

4 Configuration

Version: 2023.3.0-SNAPSHOT

Table of Contents

4.1Configuration Example
4.2Configuration Reference
4.3The Default Mapping & Constraints
4.4Hibernate Customization

4 Configuration

GORM for Hibernate can be configured with the app/conf/application.yml file when using Grails, the src/main/resources/application.yml file when using Spring Boot or by passing a Map or instanceof the PropertyResolver interface to the org.grails.orm.hibernate.HibernateDatastore class when used standalone.

All configuration options are read and materialized into an instance of HibernateConnectionSourceSettings.

4.1 Configuration Example

If you are using Grails or Spring Boot, the following is an example of configuration specified in application.yml:

dataSource:
    pooled: true
    dbCreate: create-drop
    url: jdbc:h2:mem:devDb
    driverClassName: org.h2.Driver
    username: sa
    password:
hibernate:
    cache:
        queries: false
        use_second_level_cache: true
        use_query_cache: false
        region.factory_class: org.hibernate.cache.ehcache.EhCacheRegionFactory

Each one of the settings under the dataSource block is set on the DataSourceSettings property of HibernateConnectionSourceSettings.

Whilst each setting under the hibernate block is set on the HibernateSettings property.

4.2 Configuration Reference

You can refer to the HibernateConnectionSourceSettings class for all available configuration options, but below is a table of the common ones:

name description default value

grails.gorm.flushMode

The flush mode to use

AUTO

grails.gorm.failOnError

Whether to throw an exception on validation error

false

grails.gorm.default.mapping

The default mapping to apply to all classes

null

grails.gorm.default.constraints

The default constraints to apply to all classes

null

grails.gorm.multiTenancy.mode

The multi tenancy mode

NONE

The following are common configuration options for the SQL connection:

name description default value

dataSource.url

The JDBC url

jdbc:h2:mem:grailsDB

dataSource.driverClassName

The class of the JDBC driver

detected from URL

dataSource.username

The JDBC username

null

dataSource.password

The JDBC password

null

dataSource.jndiName

The name of the JNDI resource for the DataSource

null

dataSource.pooled

Whether the connection is pooled

true

dataSource.lazy

Whether a LazyConnectionDataSourceProxy should be used

true

dataSource.transactionAware

Whether a TransactionAwareDataSourceProxy should be used

true

dataSource.readOnly

Whether the DataSource is read-only

false

dataSource.options

A map of options to pass to the underlying JDBC driver

null

And the following are common configuration options for Hibernate:

name description default value

hibernate.dialect

The hibernate dialect to use

detected automatically from DataSource

hibernate.readOnly

Whether Hibernate should be read-only

false

hibernate.configClass

The configuration class to use

HibernateMappingContextConfiguration

hibernate.hbm2ddl.auto

Whether to create the tables on startup

none

hibernate.use_second_level_cache

Whether to use the second level cache

true

hibernate.cache.queries

Whether to cache queries (see Caching Queries)

false

hibernate.cache.use_query_cache

Enables the query cache

false

hibernate.configLocations

Location of additional Hibernate XML configuration files

hibernate.packagesToScan

In addition, any additional settings that start with hibernate. are passed through to Hibernate, so if there is any specific feature of Hibernate you wish to configure that is possible.

The above table covers the common configuration options. For all configuration refer to properties of the HibernateConnectionSourceSettings class.

4.3 The Default Mapping & Constraints

The grails.gorm.default.mapping and grails.gorm.default.constraints settings deserve special mention. These define the default ORM mapping and the default Validation Constraints used by each entity.

Altering the Default Database Mapping

You may have reason to want to change how all domain classes map to the database. For example, by default GORM uses the native id generation strategy of the database, whether that be an auto-increment column or a sequence.

If you wish to globally change all domain classes to use a uuid strategy then you can specify that in the default mapping:

app/conf/application.groovy
grails.gorm.default.mapping = {
        cache true
        id generator:'uuid'
}

As you can see you can assign a closure that is equivalent to the mapping block used to customize how a domain class maps to a database table.

Because the setting is Groovy configuration it must go into a Groovy-aware configuration format. This can be app/conf/application.groovy in Grails, or src/main/resources/application.groovy in Spring Boot.

Altering the Default Constraints

For validation, GORM applies a default set of constraints to all domain classes.

For example, by default all properties of GORM classes are not nullable by default. This means a value has to be supplied for each property, otherwise you will get a validation error.

In most cases this is what you want, but if you are dealing with a large number of columns, it may prove inconvinient.

You can alter the default constraints using Groovy configuration using the grails.gorm.default.constraints setting:

app/conf/application.groovy
grails.gorm.default.constraints = {
    '*'(nullable: true, size: 1..20)
}

In the above example, all properties are allowed to be nullable by default, but limited to a size of between 1 and 20.

4.4 Hibernate Customization

If you want to hook into GORM and customize how Hibernate is configured there are a variety of ways to achieve that when using GORM.

Firstly, as mentioned previously, any configuration you specify when configuring GORM for Hibernate will be passed through to Hibernate so you can configure any setting of Hibernate itself.

For more advanced configuration you may want to configure or supply a new HibernateConnectionSourceFactory instance or a HibernateMappingContextConfiguration or both.

The HibernateConnectionSourceFactory

The HibernateConnectionSourceFactory is used to create a new Hibernate SessionFactory on startup.

If you are using Spring, it is registered as a Spring bean using the name hibernateConnectionSourceFactory and therefore can be overridden.

If you are not using Spring it can be passed to the constructor of the HibernateDatastore class on instantiation.

The HibernateConnectionSourceFactory has a few useful setters that allow you to specify a Hibernate Interceptor or MetadataContributor (Hibernate 5+ only).

The HibernateMappingContextConfiguration

HibernateMappingContextConfiguration is built by the HibernateConnectionSourceFactory, but a customized version can be specified using the hibernate.configClass setting in your configuration:

app/conf/application.yml
hibernate:
        configClass: com.example.MyHibernateMappingContextConfiguration

The customized version should extend HibernateMappingContextConfiguration and using this class you can add additional classes, packages, hbm.cfg.xml files and so on.

<< 3Quick Start Guide
5Domain Modelling in GORM >>
Quick Reference (hide)