ORM - Configuration

All ORM configuration lives in this.ormSettings inside your Application.cfc. This page covers every available setting, schema management modes, naming strategies, and custom Hibernate configuration.

For a minimal setup, see ORM - Getting Started. For logging-specific settings, see ORM - Logging and Debugging.

Quick Reference

Here's a recommended starting point for development and production:

Development:

this.ormSettings = {
	dbcreate: "dropcreate",
	cfclocation: [ "/models" ],
	logSQL: true,
	logParams: true,
	formatSQL: true,
	savemapping: true,
	flushAtRequestEnd: false
};

Production:

this.ormSettings = {
	dbcreate: "none",
	cfclocation: [ "/models" ],
	dialect: "MySQL8",
	flushAtRequestEnd: false
};

Always set flushAtRequestEnd: false in production. The default (true) means any entity you modify — even for display purposes — gets silently persisted at the end of the request. Use explicit cftransaction blocks instead. See ORM - Sessions and Transactions.

Core Settings

ormenabled

Turns ORM on for this application. Must be true for any ORM functionality to work.

this.ormEnabled = true;

Note: This is set directly on this, not inside this.ormSettings.

datasource

Which datasource ORM uses. If omitted, ORM uses the application's default datasource.

this.ormSettings = {
	datasource: "myOrmDb"
};

For using ORM with multiple datasources, see ORM - Sessions and Transactions.

cfclocation

Directory or array of directories to scan for persistent CFCs. Paths are relative to the application root.

this.ormSettings = {
	cfclocation: [ "/models", "/models/legacy" ]
};

If omitted, Lucee scans the entire application root — which works fine for small apps but slows startup on larger codebases.

dialect

The SQL dialect Hibernate uses for query generation. Always set this explicitly — auto-detection can fail with JTDS drivers or less common databases.

this.ormSettings = {
	dialect: "MySQL8"
};

You can use short names or fully qualified class names:

Many more are available — any non-abstract subclass of org.hibernate.dialect.Dialect in Hibernate 5.6 is supported. You can also pass a fully qualified class name for custom dialects.

catalog

Default database catalog for all entities. Can be overridden per-entity with the catalog component attribute.

schema

Default database schema for all entities. Can be overridden per-entity with the schema component attribute.

this.ormSettings = {
	schema: "public"
};

Schema Management

dbcreate

Controls how Hibernate manages your database schema on application startup.

Warning: "dropcreate" destroys all data on every application restart. Never use in production.

Note: "update" only adds — it will never drop a column, rename a table, or change a column type. Don't rely on it for real migrations; use a dedicated migration tool.

Note: "validate" currently checks table existence only — it does not validate individual columns or types. This is due to a limitation in Hibernate 5.6 (HHH-10882). On older Lucee versions, "create", "create-drop", and "validate" are not recognised and silently fall back to "none".

sqlscript

Path to a SQL script that runs after ORM initialisation, regardless of dbcreate mode. Commonly used with "dropcreate" to seed test data, but executes for all modes including "none". The script runs once per application start, after Hibernate's schema tool has finished.

this.ormSettings = {
	dbcreate: "dropcreate",
	sqlScript: getDirectoryFromPath( getCurrentTemplatePath() ) & "seed.sql"
};

savemapping

When true, writes the generated .hbm.xml mapping files to disk alongside your entity CFCs. Invaluable for debugging mapping issues — inspect these files to see exactly what Hibernate thinks your entities look like.

this.ormSettings = {
	savemapping: true
};

Dev only. Don't leave this on in production — it writes files on every startup.

autogenmap

When true (the default), Lucee generates Hibernate mappings automatically from your CFC properties. Set to false if you're providing your own .hbm.xml mapping files.

useDBForMapping

When true, Lucee inspects the database to determine column types, primary keys, and foreign keys. This helps Hibernate generate more accurate mappings but requires a database connection at startup.

Session & Flush Settings

flushAtRequestEnd

When true, Lucee automatically flushes (persists) all dirty entities at the end of every request. This is the most dangerous default in ORM — any entity you load and modify gets silently saved, even if you only changed it for display purposes.

// RECOMMENDED: always set to false
this.ormSettings = {
	flushAtRequestEnd: false
};

With flushAtRequestEnd: false, you control when persistence happens:

• Inside a cftransaction block (commit triggers flush)
• By calling ormFlush() explicitly

See ORM - Sessions and Transactions for details.

autoManageSession

When true, Lucee manages the ORM session lifecycle: open, flush, clear, and close. When false, your application is responsible for managing the session. The session always closes at the end of the request regardless of this setting.

Event Settings

eventHandling

Must be true for the global event handler CFC (eventHandler) to receive events. Entity-level event methods (preInsert, postUpdate, etc. defined directly in entity CFCs) fire regardless of this setting.

this.ormSettings = {
	eventHandling: true
};

See ORM - Events for the full event lifecycle.

eventHandler

Path to a global event handler CFC. This CFC receives events for all entities — useful for cross-cutting concerns like audit logging.

this.ormSettings = {
	eventHandling: true,
	eventHandler: "models.GlobalEventHandler"
};

See ORM - Events for the full list of global events.

Cache Settings

secondaryCacheEnabled

Enables Hibernate's second-level (L2) cache. The L2 cache sits between the session cache (per-request) and the database, caching entity data across requests.

cacheProvider

The cache implementation to use. Currently only "ehcache" is fully supported.

cacheconfig

Path to an ehcache.xml configuration file. Only used when secondaryCacheEnabled is true. If omitted, a default configuration is generated automatically.

this.ormSettings = {
	secondaryCacheEnabled: true,
	cacheProvider: "ehcache",
	cacheconfig: "ehcache.xml"
};

See ORM - Caching for details on configuring entity and query caching.

Logging Settings

New in 5.6. These settings control what Hibernate logs to the Lucee orm log. For full logging setup including log levels and the orm.log file, see ORM - Logging and Debugging.

logSQL

Logs SQL statements generated by Hibernate.

logParams

Logs parameter bindings for SQL statements — shows the actual values being bound to ? placeholders. Most useful alongside logSQL.

logCache

Logs second-level cache and query cache activity — hits, misses, puts, evictions.

logVerbose

Logs Hibernate internals — session lifecycle, entity loading, dirty checking. Produces a lot of output; use for targeted debugging only.

formatSQL

Pretty-prints SQL in the log output. Makes long queries readable but has a small performance cost per statement.

this.ormSettings = {
	logSQL: true,
	logParams: true,
	formatSQL: true
};

Naming Strategies

namingStrategy

Controls how CFC names and property names are translated to table and column names.

this.ormSettings = {
	namingStrategy: "smart"
};

For a custom naming strategy, create a CFC that implements convertTableName( name ) and convertColumnName( name ):

// models/MyNaming.cfc
component {

	function convertTableName( name ) {
		return "tbl_" & lCase( arguments.name );
	}

	function convertColumnName( name ) {
		return lCase( arguments.name );
	}

}

this.ormSettings = {
	namingStrategy: "models.MyNaming"
};

Error Handling Settings

skipCFCWithError

When true, persistent CFCs that have mapping errors are silently skipped instead of throwing an error at startup. Can be useful when cfclocation includes directories with work-in-progress entities.

this.ormSettings = {
	skipCFCWithError: true,
	cfclocation: [ "/models", "/models/experimental" ]
};

Use with caution. Silent failures can mask real problems.

External Hibernate Configuration

ormconfig

Path to an external hibernate.cfg.xml file. Settings from this.ormSettings take precedence over values in the XML. Connection information in the XML is ignored — Lucee always uses its own datasource pool.

this.ormSettings = {
	dbcreate: "dropcreate",
	datasource: "h2",
	ormConfig: "hibernate.cfg.xml"
};

This is useful for advanced Hibernate configuration that isn't exposed through ormSettings, like custom type registrations or Hibernate-specific properties.

Custom Hibernate Mappings

By default, Lucee generates Hibernate mapping XML from your CFC property attributes (autogenmap: true). For full control, you can provide your own .hbm.xml mapping files.

Using .cfc.hbm.xml Files

Place a mapping file alongside your entity CFC with the naming convention EntityName.cfc.hbm.xml:

/models/
    User.cfc
    User.cfc.hbm.xml

When savemapping: true, Lucee writes the auto-generated mappings to disk in this format — a good starting point for customisation.

Hybrid Approach

You can mix auto-generated and custom mappings. Set autogenmap: true (the default), and Lucee will use your .hbm.xml file when it exists, or generate mappings from CFC properties when it doesn't.

Via hibernate.cfg.xml

You can also define mappings in an external hibernate.cfg.xml file via the ormConfig setting. This gives you access to the full Hibernate mapping DSL.

All Settings at a Glance

See also

• ORM
• ORM - Caching
• ORM - Entity Mapping
• ORM - Events
• ORM - Getting Started
• ORM - Logging and Debugging
• ORM - Migration Guide
• ORM - Sessions and Transactions
• ORM - Troubleshooting
• Application.cfc / <cfapplication>