Configuration

Easily configure Hibernate with CFML

Application.cfc

The ORM can be configured by a struct of settings set in this.ormSettings in your main Application.cfc:

component{
    this.ORMenabled = true;
    this.ormSettings = {
        // << Here Be ORM Configuration! 🤪 >>
    };
}

ORM Settings

The full list of available properties you can use to configure the ORM are the following:

Setting Name	Default	Description
autoGenMap	true	Specifies whether ColdFusion should automatically generate entity mappings for the persistent CFCs. If autogenmap=false, the mapping should be provided in the form of .HBMXML files.
autoManageSession	true	Allows the engine to manage the Hibernate session. It is recommended not to let the engine manage it for you. Use transaction blocks in order to demarcate your regions that should start, flush and end a transaction. https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#transactions
cacheConfig	true	Specifies the location of the configuration file that the secondary cache provider should use. This setting is used only when secondaryCacheEnabled=true. See Secondary Cache below.
cacheProvider	"ehcache"	Specifies the cache provider that ORM should use as a secondary cache. The values can be: Ehcache ConcurrentHashMap The fully qualified name of the class for any other cache provider. See Secondary Cache below.
catalog		Specifies the default Database Catalog that ORM should use.
cfclocation	empty	Specifies the directory (or array of directories) that should be used to search for persistent CFCs to generate the mapping. Always specify it or pay a performance startup price. Important: If it is not set, the extension looks at the application directory, its sub-directories, and its mapped directories to search for persistent CFCs.
datasource	application.datasource	This setting defines the data source to be utilized by the ORM. If not used, defaults to the this.datasource in the Application.cfc
dbcreate	none	update : Creates the database according to your ORM model. It only does incremental updates. It will never remove tables, indexes, etc. dropcreate : Same as above but it destroys the database if it has ny content and recreates it every time the ORM is reloaded. none : Does not change the database at all.
dialect	autodiscover	The dialect to use for your database. By default Hibernate will introspect the datasource and try to figure it out. See the dialects section below. You can also use the fully Java qualified name of the class. See the dialects section below.
eventHandling	false	If true, then it enables the ORM event callbacks in entities and globally via the eventHandler
eventHandler		The CFC path of the CFC that will manage the global ORM events.
flushAtRequestEnd	true	Specifies if an orm flush should be called automatically at the end of a request. In our opinion this SHOULD never be true. A database persistence should be done via transaction tags and good transaction demarcation.
logSQL	false	Specifies if the SQL queries should be logged to the console.
namingstrategy	default	Defines the naming convention to use on table and column names. - default : Uses the table or column names as is - smart : This strategy changes the logical table or column name to uppercase. - CFC PATH : Use your own CFC to determine naming - see Custom Naming Strategy.
ormconfig		The path to a custom Hibernate configuration file: - hibernate.properties - hibernate.cfc.xml Please see Custom Hibernate Config
savemapping	false	If enabled, the ORM will create the Hibernate mapping XML (*.hbmxml) files alongside the entities. This is great for debugging your entities and relationships.
schema		The default database schema to use
secondaryCacheEnabled	false	Enable the secondary cache or not. See our Caching section.
skipCFCWithError	false	If true, then the ORM will ignore CFCs that have compile time errors in them. Use false to throw exceptions.
sqlScript		Path to a SQL script file that will be executed after the ORM is initialized. A great way to seed a database.
useDBForMapping	true	Specifies whether the database has to be inspected to identify the missing information required to generate the Hibernate mapping. The database is inspected to get the column data type, primary key and foreign key information.

Dialects

By using the ormsettings.dialect you can tell Hibernate which specific database dialect to use for building queries. By default, Hibernate tries to inspect the datasource and define it for you. 95% of the time, this works. However, if you want a specific one, then you can use the following names or a fully qualified Java class name.

Dialect (short name)	Remarks
Cache71	Support for the Caché database, version 2007.1.
CockroachDB192	Support for the CockroachDB database version 19.2.
CockroachDB201	Support for the CockroachDB database version 20.1.
CUBRID	Support for the CUBRID database, version 8.3. May work with later versions.
DB2	Support for the DB2 database, version 8.2.
DB297	Support for the DB2 database, version 9.7.
DB2390	Support for DB2 Universal Database for OS/390, also known as DB2/390.
DB2400	Support for DB2 Universal Database for iSeries, also known as DB2/400.
DB2400V7R3	Support for DB2 Universal Database for i, also known as DB2/400, version 7.3
DerbyTenFive	Support for the Derby database, version 10.5
DerbyTenSix	Support for the Derby database, version 10.6
DerbyTenSeven	Support for the Derby database, version 10.7
Firebird	Support for the Firebird database
FrontBase	Support for the Frontbase database
H2	Support for the H2 database
HANACloudColumnStore	Support for the SAP HANA Cloud database column store.
HANAColumnStore	Support for the SAP HANA database column store, version 2.x. This is the recommended dialect for the SAP HANA database. May work with SAP HANA, version 1.x
HANARowStore	Support for the SAP HANA database row store, version 2.x. May work with SAP HANA, version 1.x
HSQL	Support for the HSQL (HyperSQL) database
Informix	Support for the Informix database
Ingres	Support for the Ingres database, version 9.2
Ingres9	Support for the Ingres database, version 9.3. May work with newer versions
Ingres10	Support for the Ingres database, version 10. May work with newer versions
Interbase	Support for the Interbase database.
JDataStore	Support for the JDataStore database
McKoi	Support for the McKoi database
Mimer	Support for the Mimer database, version 9.2.1. May work with newer versions
MySQL5	Support for the MySQL database, version 5.x
MySQL5InnoDB	Support for the MySQL database, version 5.x preferring the InnoDB storage engine when exporting tables.
MySQL57InnoDB	Support for the MySQL database, version 5.7 preferring the InnoDB storage engine when exporting tables. May work with newer versions
MariaDB	Support for the MariaDB database. May work with newer versions
MariaDB53	Support for the MariaDB database, version 5.3 and newer.
Oracle8i	Support for the Oracle database, version 8i
Oracle9i	Support for the Oracle database, version 9i
Oracle10g	Support for the Oracle database, version 10g
Pointbase	Support for the Pointbase database
PostgresPlus	Support for the Postgres Plus database
PostgreSQL81	Support for the PostgrSQL database, version 8.1
PostgreSQL82	Support for the PostgreSQL database, version 8.2
PostgreSQL9	Support for the PostgreSQL database, version 9. May work with later versions.
Progress	Support for the Progress database, version 9.1C. May work with newer versions.
SAPDB	Support for the SAPDB/MAXDB database.
SQLServer	Support for the SQL Server 2000 database
SQLServer2005	Support for the SQL Server 2005 database
SQLServer2008	Support for the SQL Server 2008 database
Sybase11	Support for the Sybase database, up to version 11.9.2
SybaseAnywhere	Support for the Sybase Anywhere database
SybaseASE15	Support for the Sybase Adaptive Server Enterprise database, version 15
SybaseASE157	Support for the Sybase Adaptive Server Enterprise database, version 15.7. May work with newer versions.
Teradata	Support for the Teradata database
TimesTen	Support for the TimesTen database, version 5.1. May work with newer versions

See the Hibernate Dialect Section: https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#database-dialect

Sample Config

Here is an example configuration from the popular ContentBox Modular CMS application

// THE CONTENTBOX DATASOURCE NAME
this.datasource  = "contentbox";
// ORM SETTINGS
this.ormEnabled  = true;
// cfformat-ignore-start
this.ormSettings = {
	// ENTITY LOCATIONS, ADD MORE LOCATIONS AS YOU SEE FIT
	cfclocation           : [
		// If you create your own app entities
		"models",
		// The ContentBox Core Entities
		"modules/contentbox/models",
		// Custom Module Entities
		"modules_app",
		// Custom Module User Entities
		"modules/contentbox/modules_user"
	],
	// THE DIALECT OF YOUR DATABASE OR LET HIBERNATE FIGURE IT OUT, UP TO YOU TO CONFIGURE.
	dialect              : request.$systemHelper.getSystemSetting( "ORM_DIALECT", "" ),
	// DO NOT REMOVE THE FOLLOWING LINE OR AUTO-UPDATES MIGHT FAIL.
	dbcreate             : "update",
	secondarycacheenabled: request.$systemHelper.getSystemSetting( "ORM_SECONDARY_CACHE", false ),
	cacheprovider        : request.$systemHelper.getSystemSetting( "ORM_SECONDARY_CACHE", "ehCache" ),
	logSQL               : request.$systemHelper.getSystemSetting( "ORM_LOGSQL", false ),
	sqlScript            : request.$systemHelper.getSystemSetting( "ORM_SQL_SCRIPT", "" ),
	// ORM SESSION MANAGEMENT SETTINGS, DO NOT CHANGE
	flushAtRequestEnd    : false,
	autoManageSession    : false,
	// ORM EVENTS MUST BE TURNED ON FOR CONTENTBOX TO WORK DO NOT CHANGE
	eventHandling        : true,
	eventHandler         : "cborm.models.EventHandler",
	// THIS IS ADDED SO OTHER CFML ENGINES CAN WORK WITH CONTENTBOX
	skipCFCWithError     : true,
	// TURN ON FOR Debugging if ORM mappings are not working.
	savemapping          : false
};

Custom Naming Strategy

You can define your own naming convention for table and column names by pointing this.ormSettings.namingStrategy to a custom CFC path:

this.ormSettings = {
	// ...
	namingStrategy : "models.orm.UnderscoreNamingStrategy"
}

The UnderscoreNamingStrategy.cfc component should then define two methods: getTableName() and getColumnName():

// models/orm/UnderscoreNamingStrategy.cfc
component{
	function getTableName( string tableName ){
		// funky table name conversion here...
	}

	function getColumnName( string columnName ){
		// funky column name conversion here...
	}
}