Bx Orm Entities

bx-orm: Entities & Properties

Defining a Persistent Entity

// Minimal entity — table name defaults to class file name
class persistent="true" {

}

// With explicit entity name and table
class persistent="true" entityName="Author" table="authors" {

}

Entity Annotations

Defining Properties

All properties inside a persistent=true class are persistent by default:

class persistent="true" entityName="User" table="users" {

    // Primary key
    property name="id" fieldtype="id" type="numeric" generator="native";

    // Basic string column
    property name="username" type="string";

    // With explicit column name
    property name="createdAt" column="created_at" type="date" ormtype="timestamp";

    // Non-persistent (ignored by ORM)
    property name="transientHelper" persistent="false";

    // With default value (BoxLang side only, not DB-level)
    property name="isActive" type="boolean" default="true";

    // With DB-level default
    property name="createdOn" ormtype="datetime" dbdefault="'2024-01-01'";

    // Not-null constraint
    property name="email" type="string" notnull="true";

}

Property Annotations Reference

Identifiers (Primary Keys)

// Auto-increment (native — recommended)
property name="id" fieldtype="id" type="numeric" generator="native";

// UUID primary key
property name="id" fieldtype="id" type="string" generator="uuid";

// Assigned (you set the ID manually)
property name="id" fieldtype="id" type="string" generator="assigned";

// Sequence (for Oracle/PostgreSQL)
property name="id"
    fieldtype="id"
    type="numeric"
    generator="sequence"
    sequence="seq_users";

Generator values: native, identity, uuid, assigned, sequence, increment, hilo.

Composite Primary Keys

class persistent="true" entityName="OrderItem" table="order_items" {

    property name="orderId"   fieldtype="id" type="numeric" column="order_id";
    property name="productId" fieldtype="id" type="numeric" column="product_id";

    property name="quantity" type="numeric";
    property name="price"    type="numeric" ormtype="big_decimal";

}

Version / Optimistic Locking

class persistent="true" entityName="Product" {

    property name="id"      fieldtype="id" generator="native";
    property name="name"    type="string";
    property name="version" fieldtype="version" type="numeric";

}
// Hibernate increments version on every update.
// Throws StaleObjectStateException if two sessions modify the same row.

Timestamp Auto-Fields

property name="createdAt"  fieldtype="timestamp" generated="insert";
property name="updatedAt"  fieldtype="timestamp" generated="always";

Full Entity Example

class persistent="true" entityName="Post" table="blog_posts" {

    property name="id"
        fieldtype = "id"
        type      = "numeric"
        generator = "native";

    property name="title"
        type     = "string"
        length   = 200
        notnull  = "true";

    property name="body"
        type    = "string"
        ormtype = "text";

    property name="status"
        type    = "string"
        length  = 20
        default = "draft";

    property name="publishedAt"
        column  = "published_at"
        type    = "date"
        ormtype = "timestamp";

    property name="createdAt"
        column    = "created_at"
        ormtype   = "datetime"
        insert    = "true"
        update    = "false"
        dbdefault = "CURRENT_TIMESTAMP";

}

Common Pitfalls

• ❌ Do NOT omit generator on fieldtype="id" — use native for auto-increment
• ❌ Do NOT use type="date" when you need full datetime — use ormtype="timestamp"
• ❌ Quote datetime dbdefault values: dbdefault="'2024-01-01'" (MySQL requires single-quoted strings)
• ✅ Use persistent="false" for calculated properties or transient helpers
• ✅ Use dynamicUpdate="true" on large entities where only a few columns change per save
• ✅ Use insert="false" update="false" on columns that are managed by DB triggers