> For the complete documentation index, see [llms.txt](https://coldbox-orm.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox-orm.ortusbooks.com/v5.x/getting-started/installation.md).

# Installation

Quickly install cborm

Leverage CommandBox to install into your ColdBox app:

```bash
# Latest version
install cborm

# Bleeding Edge
install cborm@be
```

### Trying the cborm 6 Pre-Release

Before 6.0.0 is final, pre-releases are published for testing: `6.0.0-beta.1`, `6.0.0-beta.2`, and so on (later `6.0.0-rc.1`). A plain `install cborm` keeps installing the latest stable release, so ask for the pre-release by version, together with a bx-orm 2 pre-release:

```bash
install cborm@6.0.0-beta.1
install bx-orm@2.0.0-beta.1
```

The pre-releases and their notes are on the [cborm releases page](https://github.com/coldbox-modules/cborm/releases) and the [bx-orm releases page](https://github.com/ortus-boxlang/bx-orm/releases). They are for testing, not production: please report what you find on the [issue tracker](https://ortussolutions.atlassian.net/browse/CBORM).

## System Requirements

* BoxLang 1.18.0+
* The [bx-orm](https://forgebox.io/view/bx-orm) module 2.x (Hibernate 7.4)
* ColdBox 8+
* CFML applications: the `bx-compat-cfml` module, so your `.cfc` code runs on BoxLang

{% hint style="warning" %}
cborm 6 is a pure BoxLang module. Adobe ColdFusion and Lucee are **not** supported: stay on the cborm 5.x series for those engines. See [Upgrading to 6](/v5.x/intro/release-history/upgrading-to-6.md).
{% endhint %}

Install the ORM module into your BoxLang runtime or server:

```bash
install bx-orm
```

## Application Setup

Enable the ORM in your `Application.bx` (or `Application.cfc`) and point it at the cborm event handler. If you are using the ORM event handler, `ActiveEntity` or any ColdBox proxies that require ORM, you must also create an application mapping to the module, because the ORM starts before ColdBox registers its module paths.

{% code title="Application.bx" %}

```javascript
class {

    this.name = "MyApp";

    // cborm mapping: the ORM boots before ColdBox registers module paths
    this.mappings[ "/cborm" ] = COLDBOX_APP_ROOT_PATH & "modules/cborm";

    this.datasource  = "myDatasource";
    this.ormEnabled  = true;
    this.ormSettings = {
        // Where your entities live
        entityPaths    : [ "models" ],
        dbcreate       : "update",
        // Let cborm announce ORM events to ColdBox interceptors and autowire entities
        eventHandling  : true,
        eventHandler   : "cborm.models.EventHandler",
        // Let ColdBox or your services manage flushing
        flushAtRequestEnd : false
    };

}
```

{% endcode %}

{% hint style="info" %}
`cborm.models.BXEventHandler` still works as a deprecated alias of `cborm.models.EventHandler`. Every other ORM setting is documented in the bx-orm module's documentation.
{% endhint %}

## WireBox DSL

The module registers a new WireBox DSL called `entityservice` which can produce virtual or base ORM entity services. Below are the injections you can use:

* `entityservice` - Inject a global ORM service
* `entityservice:{entityName}` - Inject a Virtual entity service according to `entityName`

## Module Settings

Here are the module settings you can place in your `ColdBox.cfc` under `moduleSettings` -> `cborm` structure or by creating a `cborm.cfc` in the `config/modules` directory.

{% code title="config/ColdBox.cfc" %}

```javascript
moduleSettings = {
    cborm = {
        // Resource Settings
    		resources : {
    			// Enable the ORM Resource Event Loader
    			eventLoader 	: false,
    			// Pagination max rows
    			maxRows 		: 25,
    			// Pagination max row limit: 0 = no limit
    			maxRowsLimit 	: 500
    		},
        // WireBox Injection bridge
        injection = {
            // enable entity injection via WireBox
            enabled = true,
            // Which entities to include in DI ONLY, if empty include all entities
            include = "",
            // Which entities to exclude from DI, if empty, none are excluded
            exclude = ""
        }
    }
}
```

{% endcode %}

ColdBox 7+ Config:

{% tabs %}
{% tab title="BoxLang" %}
{% code title="config/modules/cborm.bx" lineNumbers="true" %}

```javascript
class{
  function configure(){
     return {
        // Resource Settings
        resources : {
            // Enable the ORM Resource Event Loader
            eventLoader : false,
            // Pagination max rows
            maxRows : 25,
            // Pagination max row limit: 0 = no limit
            maxRowsLimit : 500
        },
            // WireBox Injection bridge
            injection : {
                // enable entity injection via WireBox
                enabled : true,
                // Which entities to include in DI ONLY, if empty include all entities
                include : "",
                // Which entities to exclude from DI, if empty, none are excluded
                exclude : ""
            }
      }
    }
}
```

{% endcode %}
{% endtab %}

{% tab title="CFML" %}
{% code title="config/modules/cborm.cfc" lineNumbers="true" %}

```javascript
component{
  function configure(){
     return {
        // Resource Settings
        resources : {
            // Enable the ORM Resource Event Loader
            eventLoader : false,
            // Pagination max rows
            maxRows : 25,
            // Pagination max row limit: 0 = no limit
            maxRowsLimit : 500
        },
            // WireBox Injection bridge
            injection = {
                // enable entity injection via WireBox
                enabled = true,
                // Which entities to include in DI ONLY, if empty include all entities
                include = "",
                // Which entities to exclude from DI, if empty, none are excluded
                exclude = ""
            }
      };
    }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Validation

We have also integrated a `UniqueValidator` from the **validation** module into our ORM module. It is mapped into WireBox as `UniqueValidator@cborm` so you can use it in your model constraints like so:

```javascript
{ fieldName : { validator: "UniqueValidator@cborm" } }
```

## Hibernate Version

Hibernate is bundled with the `bx-orm` module. cborm 6 runs on `bx-orm` 2, which bundles Hibernate ORM 7.4: <https://hibernate.org/orm/documentation/7.4/>

{% hint style="info" %}
**Automatic value conversion**: bx-orm converts values to the Java types Hibernate expects, so cborm no longer casts values itself. `idCast()` and `autoCast()` remain for compatibility and do not cast.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://coldbox-orm.ortusbooks.com/v5.x/getting-started/installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.