bx-orm: Configuration

Enabling ORM in Application.bx

class {

    this.datasource = "myApp"  // default datasource for ORM

    this.ORMenabled = true
    this.ormSettings = {
        // required — always specify to avoid startup performance hit
        entityPaths          : [ "models/entities" ],

        // database schema management
        dbcreate             : "update",      // none | update | dropcreate

        // performance & debugging
        logSQL               : false,
        savemapping          : false,         // save .hbmxml files (debug only)
        ignoreParseErrors    : false,

        // session management (recommended settings)
        autoManageSession    : false,         // manage sessions yourself via transaction{}
        flushAtRequestEnd    : false,         // don't auto-flush; use explicit transactions

        // event system
        eventHandling        : false,
        eventHandler         : "",            // path to global event handler class
    }

}

dbcreate Options

Recommendation: Use update in development, none in production (use DB migrations instead).

Key Settings Reference

Production-Ready Configuration

class {

    this.datasource = "myApp"

    this.ORMenabled = true
    this.ormSettings = {
        entityPaths          : [ "models" ],
        dbcreate             : "none",          // use DB migrations in production
        flushAtRequestEnd    : false,           // explicit transactions only
        autoManageSession    : false,           // manage sessions yourself
        eventHandling        : true,
        eventHandler         : "models.ORMEventHandler",
        secondaryCacheEnabled: true,
        cacheProvider        : "Ehcache",
        cacheConfig          : "./config/ehcache.xml",
        logSQL               : false,
        ignoreParseErrors    : false
    }

}

Dialect Configuration

Let Hibernate auto-detect (works 95% of the time), or specify explicitly:

this.ormSettings = {
    dialect: "MySQL57InnoDB"    // explicit dialect
    // dialect: "PostgreSQL9"
    // dialect: "SQLServer2008"
    // dialect: "Oracle10g"
    // dialect: "H2"
}

Common dialects: MySQL5InnoDB, MySQL57InnoDB, MariaDB, PostgreSQL9, SQLServer2008, Oracle10g, H2, HSQL.

Multiple Datasources

this.ormSettings = {
    entityPaths: [ "models/primary", "models/reporting" ],
    datasource : "primary"   // default; individual entities can override
}

Override per-entity:

class persistent="true" datasource="reporting" {
    // ...
}

ORM Reload (Development)

Force a full reload of ORM mappings (clears entity cache):

ORMReload()

Useful after adding entities or changing mappings during development.

Common Pitfalls

• ❌ Do NOT omit entityPaths — it will scan the entire application tree (very slow)
• ❌ Do NOT use flushAtRequestEnd=true in production — leads to unpredictable saves
• ❌ Do NOT use autoManageSession=true when using explicit transaction{} blocks
• ✅ Always use explicit transaction {} blocks to demarcate database writes
• ✅ Set logSQL=true temporarily to debug unexpected queries
• ✅ Use savemapping=true temporarily to inspect Hibernate XML mappings when debugging