Data & Persistence

Database access in ColdBox — ORM options (BoxLang ORM, cborm, Quick), the qb query builder, and cfmigrations.

ColdBox is persistence-agnostic: you choose the data layer per project. The ecosystem offers three ORM paths, a fluent query builder, and migrations.

Choosing an ORM

Option	Engine	Best for
BoxLang ORM (bx-orm)	BoxLang	New BoxLang apps — native, first-class
cborm	Adobe / Lucee / BoxLang-CFML	Existing Hibernate ORM apps, virtual service layers, criteria queries
Quick	All	Lightweight entity ORM without Hibernate

box install bx-orm      # BoxLang native
box install cborm       # Hibernate-based
box install quick       # Lightweight entities

📖 Full documentation: bxorm.ortusbooks.com · cborm.ortusbooks.com · quick.ortusbooks.com

Quick Example (Quick)

BoxLang

// models/User.bx
class extends="quick.models.BaseEntity" {

    property name="email"
    property name="name"

}

CFML

// models/User.cfc
component extends="quick.models.BaseEntity" {

    property name="email"
    property name="name"

}

// In a handler or service
property name="userService" inject="quickService:User";

users = userService.where( "active", true ).orderBy( "name" ).get()
user  = userService.findOrFail( rc.id )

qb — Fluent Query Builder

When an ORM is more than you need, qb gives you expressive, injection-safe SQL:

box install qb

property name="query" inject="QueryBuilder@qb";

var activeUsers = query.from( "users" )
    .where( "active", true )
    .orderBy( "created", "desc" )
    .limit( 20 )
    .get()

📖 Full documentation: qb.ortusbooks.com

cfmigrations — Versioned Schema Changes

box install cfmigrations

# Create and run migrations
migrate create create_users_table
migrate up

Migrations keep schema changes in source control and apply them consistently across environments — the same files power CbGenesis, our production starter template.

📖 Full documentation: cfmigrations.ortusbooks.com

See Also

• Serialization — turning entities into API responses

• Models — the service layer and dependency injection

• Testing Tools — cbMockData for seeding test data