6.0.0

• Add compatibility with ColdBox 7.

• Fixed a bug where once a virtual attribute was added to an entity it was added to all future entities of that same type.

• Dropped support for ColdBox 5.

5.3.3

Use correct nesting for where statements

5.3.2

Fixed retrieving null values from fields and relationships

5.3.1

• Special handling for Lucee generated keys

• Workaround for adobe@2021 not supporting null values in param statements

• Upgrade to latest cfmigrations (v4.0.0)

5.3.0

Add a way to not fire events inside a callback using withoutFiringEvents.

5.2.11

Upgrade to qb 9

5.2.10

HasOneOrManyThrough: Fix too many joins for has and whereHas

5.2.9

HasOneOrManyThrough: Fixed applying of through constraints BaseEntity: Use wirebox to get the util to work in CommandBox

5.2.8

Fix bad link to Getting Started guide

5.2.7

Use existing builder when adding subselects

5.2.6

Update to latest mementifier (v3.0.0)

5.2.5

CommandBox compatibility

5.2.4

Force generated key to be an integer.

5.2.3

CommandBox-friendly injections using the box namespace.

5.2.2

Fixed regression where eager loading inside a relationship was broken.

5.2.1

Fixed accessing QuickBuilder from entities and relationships.

5.2.0

Add include and exclude arguments to fill method.

5.1.3

Always return numeric value for AutoIncrementingKeyType.

5.1.2

Add the builder to the preInsert method for ReturningKeyType.

5.1.1

Set the table when creating new queries.

5.1.0

Added support for single-table inheritance (STI) with discriminated subclass entities.

5.0.0

In 5.0.0, we stepped up the performance of Quick in a major way. Entity creation is now over twice as fast as before.

Performance Improvements

Average duration to create one entity:

While the times may seem small, this is compounded for each entity you create. So, if you are retrieving 1000 entities, multiply each of these numbers by 1000 and you'll start to see why this matters.

This did introduce one breaking change from v4. See the Upgrade Guide for more information.

New Features

• Added a new RowIDKeyType that will correctly set your primary key if your database only returns ROWID in the queryExecute response.

Bug Fixes

• Fixed a null check in isNullValue.

• Fixed nulls coming back as strings in JsonCast.

4.2.0

• Add a simplePaginate pagination method for quicker performance when total records or total pages are not needed or too slow.

4.1.6

• Configure columns are no longer cleared when setting up a BelongsToMany relationship.

4.1.5

• Provide initialThroughConstraints for hasOne relationships (used in *Through relationships).

4.1.4

• Ignore orders when retrieving a relationship count.

4.1.1, 4.1.2

• Preserve casted value after saving an entity.

4.1.0

• Allow for child entities, including discriminated entities.

• Look up returning values by column name not by alias in the ReturningKeyType.

4.0.2

• Skip eager loading database call when no keys are found.

• Only apply CONCAT when needed in *Through relationships.

4.0.1

• Use WHERE EXISTS over DISTINCT when fetching relationships. DISTINCT restricts some of the queries that can be run.

4.0.0

BREAKING CHANGES

• Scopes, whereHas, and whereDoesntHave callbacks now automatically group where clauses when an OR combinator is detected.

Other Changes

• Dynamically add relationship counts to a parent entity without loading all of the relationship.

• Give a helpful error message when trying to set relationship values before saving an entity, where applicable.

• Multiple bug fixes related to subselects and querying relationships when using belongsToThrough, hasOneThrough, or hasManyThrough.

3.1.7

• Correct jQuery link in test runner.

3.1.6

• Allow expressions in basic where clauses.

• Fix delete naming collision.

3.1.5

• Add an alias to with to QuickBuilder.

3.1.4

• Fix a stack overflow on nested relationship checks.

3.1.3

• Configured tables (.from) are now used for qualifying columns.

3.1.2

• Remove unnecessary nesting in compare queries.

3.1.1

• Fix querying relationship methods when using "OR" combinators.

3.1.0

• Add support for JSON casting using a new JsonCast@quick component.

3.0.4

• Compatibility updates for ColdBox 6

3.0.3

• Optimize cast caching

3.0.2

• Apply custom sqltypes during eager loading.

3.0.1

• Account for null values in fill.

• Swap structAppend order for a Lucee bug in mementifier integration.

3.0.0

BREAKING CHANGES

Please see the Upgrade Guide for more information on these changes.

• Drop support for Lucee 4.5 and Adobe ColdFusion 11.

• Virtual Inheritance (using a quick annotation instead of extending quick.models.BaseEntity) has been removed. It was hardly used, and removing it allows us to simplify some of the code paths.

• accessors="true" is now required on every entity. This is similar to above where requiring it allows us to simplify the codebase immensely. A helpful error message will be thrown if accessors="true" is not present on your entity.

• The defaultGrammar mapping needs to be the full WireBox mapping, including the @qb, if needed.

  • For instance, MSSQLGrammar would become MSSQLGrammar@qb.

  • This will allow for other grammars to be more easily contributed via third party modules.

• HasManyThrough relationships now only accept a relationships parameter of relationship methods to walk to get to the intended entity.

• Attributes using casts="boolean" need to be updated to casts="BooleanCast@quick".

• Some method and parameter names have been changed to support composite keys. The majority of changes will only affect you if you have extended base Quick components. The full list can be found in the Upgrade Guide.

Other Changes

• Bundle Mementifier for memento transformations.

• Use asMemento to automatically convert queries to mementos.

• Automatically-generated API docs.

• Add error message for defaulting key values.

• Update to qb 7.0.0.

• Add a belongsToThrough relationship.

• Add a HasOneThrough relationship.

• Custom Casts - using custom components to represent one or more attributes.

• Ordering by relationship attributes.

• addSubselect improvements.

• Add a new QuickBuilder to better handle interop with qb.

• Add exists and existsOrFail methods.

• Allow custom error messages for orFail methods.

• Ensure loadRelationship doesn't reload existing relationships.

• Add multiple retrieve or new/create methods - firstWhere, firstOrNew, firstOrCreate, findOrNew, and findOrCreate.

• Add paginate to Quick.

• Add is and isNot to compare entities.

• Allow hydrating entities from serialized data.

• Allow returning default entities for null relations on HasOne, BelongsTo, HasOneThrough, and BelongsToThrough relationships.

• Query relations using has, doesntHave, whereHas, and whereDoesntHave.

• Split reset into reset and resetToNew methods.

• Store the original attributes for later resetting.

• Use parameterLimits to eager load.

• Use a new entity each time on BaseService.

• Apply sql types for columns to wheres.

• Apply global scopes more consistently

• Correctly ignore key column when updating.

• Fix hasRelationship method to only return true for exact matches.

• Better handling of constrained relationships when eager loading.

• Convert aliases when qualifying columns.

• Add a better error message if onMissingMethod fails.

• Only retrieve columns for defined attributes.

• Cache entity metadata in CacheBox.

• Use attribute hash for checking isDirty.

2.5.0

• Define custom collections per entity.

2.4.0

• Apply custom setters when hydrating from the database. (Reverted in 2.5.3 for unintended consequences with things like password hashing.)

• Query scopes can return any value. This allows you to use scopes to perform query functions and return values. (If you do not want to return a custom value, return the QueryBuilder instance or nothing.)

• Improve error messages for not loaded entities.

• Return the correct memento with accessors on.

2.3.0

• Option to ignore non-existent attributes

2.2.0

• Relationship Fetch Methods (first and find methods)

2.1.0

• Subselect Helper

• Global Scopes

• saveMany

• Mapping foreign keys for relationships is now optional

• Either entities or primary key values can be passed to relationship persistance methods

• Relationships can also be saved by calling "set" & relationshipName

• Virtual Inheritance works on ColdBox 5.2+

A CFML ORM Engine

Why?

Quick was built out of lessons learned and persistent challenges in developing complex RDBMS applications using built-in Hibernate ORM in CFML.

• Hibernate ORM error messages often obfuscate the actual cause of the error

  because they are provided directly by the Java classes.

• Complex CFML Hibernate ORM applications can consume significant memory and

  processing resources, making them cost-prohibitive and inefficient when used

  in microservices architecture.

• Hibernate ORM is tied to the engine releases. This means that updates come

  infrequently and may be costly for non-OSS engine users.

• Hibernate ORM is built in Java. This limits contributions from CFML

  developers who don't know Java or don't feel comfortable contributing to a

  Java project.

• Hibernate ORM doesn't take advantage of a lot of dynamic- and

  meta-programming available in CFML. (Tools like CBORM have helped to bridge

  this gap.)

We can do better.

What?

Quick is an ORM (Object Relational Mapper) written in CFML for CFML. It provides an ActiveRecord implementation for working with your database. With it you can map database tables to components, create relationships between components, query and manipulate data, and persist all your changes to your database.

Prerequisites

You need the following configured before using Quick:

• Configure a default datasource in your CFML engine

• ColdBox 4.3+

• Add a mapping for quick in your Application.cfc

• Configure your BaseGrammar in config/ColdBox.cfc

See Getting Started for more details.

Supported Databases

Quick supports all databases supported by qb.

Example

Here's a "quick" example to whet your appetite.

We'll show the database structure using a migrations file. This isn't required to use quick, but it is highly recommended.

// 2017_11_10_122835_create_users_table.cfc
component {

    function up() {
        schema.create( "users", function( table ) {
            table.increments( "id" );
            table.string( "username" ).unique();
            table.string( "email" ).unique();
            table.string( "password" );
            table.timestamp( "createdDate" );
            table.timestamp( "updatedDate" );
        } );
    }

}

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

    // the name of the table is the pluralized version of the model
    // all fields in a table are mapped by default
    // both of these points can be configured on a per-entity basis

}

// handlers/Users.cfc
component {

    // /users/:id
    function show( event, rc, prc ) {
        // this finds the User with an id of 1 and retrieves it
        prc.user = getInstance( "User" ).findOrFail( rc.id );
        event.setView( "users/show" );
    }

}

<!-- views/users/show.cfm -->
<cfoutput>
    <h1>Hi, #prc.user.getUsername()#!</h1>
</cfoutput>

Now that you've seen an example, dig in to what you can do with Quick!

Prior Art, Acknowledgements, and Thanks

Quick is backed by qb. Without qb, there is no Quick.

Quick is inspired heavily by Eloquent in Laravel. Thank you Taylor Otwell and the Laravel community for a great library.

Development of Quick is sponsored by Ortus Solutions. Thank you Ortus Solutions for investing in the future of CFML.

Discussion & Help

The Box products community for further discussion and help can be found here: https://community.ortussolutions.com/c/communities/quick-orm/23

Configure a default datasource in your CFML engine

You can do this any way you'd like: through the web admin, in Application.cfc, or using .

Make sure to set this.datasource in your Application.cfc so Quick knows which datasource to use.

Download Quick

The easiest way to download Quick is to use ForgeBox with CommandBox. Just run the following from the root of your application:

box install quick

Add a mapping for quick in your Application.cfc

For a default installation in a ColdBox template, the following line will do the trick.

this.mappings[ "/quick" ] = COLDBOX_APP_ROOT_PATH & "/modules/quick";

Configure your defaultGrammar in config/ColdBox.cfc

Quick will auto discover your grammar by default on startup. To avoid this check, set a BaseGrammar.

defaultGrammar is a module setting for Quick. Set it in your config/ColdBox.cfc like so:

By default, Quick supports basic component-level inheritance of entities, meaning that a child component inherits the properties ( and ability to overload ) its parent. A common, object-oriented relational database pattern, however is to provide additional definition on parent tables ( and classes ) within child tables which contain a foreign key.

Quick supports two types of child classes: Discriminated and Subclassed child entities. In both cases, loading any child class will also deliver the data of its parent class.

Subclass Entities

Let's say, for example, that I have a Media entity, which is used to catalog and organize all media items loaded in to my application.

My Media entity contains all of the properties which are common to every media item uploaded in to my application. Let's say, however, that I need to have specific attributes that are available on only media for my Book entity ( e.g. whether the image is the cover photo, for example ). I can create a child class of BookMedia which extends my Media entity. When loaded, all of the properties of Media will be loaded along with the custom attributes which apply to my BookMedia object:

Note the additional component attribute joincolumn. The presence of this attribute on a child class signifies that it is a child entity of the parent and that the parent's properties should be loaded whenever the BookMedia entity is loaded. In addition, the primary key of the entity is that of the parent.

Child entities can be retrieved by queries specific to their own properties:

Or properties on the parent class can be used as first-class properties within the query:

Child entities can be retrieved, individually, using the value of the joinColumn, which should be a foreign key to the parent identifier column:

Now my Book entity can use its extended media class to retrieve media items which are specific to its own purpose:

Discriminated Entities

A discriminated child class functions, basically, in the same way as a subclassed entity, with one exception: The parent entity is aware of the discriminated child due to a discriminatorValue attribute and will return a specific subclass when a retrieval is performed through the parent Entity. This pattern is also known as polymorphic association.

Quick supports two different types of discriminated entities defined by single-table inheritance (STI) or multi-table inheritance (MTI). Your database schema will determine the most appropriate inheritance pattern for your use case.

Let's take our BookMedia class again, but this time, define it as a discriminated entity.

The first step is to add the discriminatorColumn attribute to the Media entity, which is used to differentiate the subclass entities. Next, define an array of possible discriminated entities for the parent. This is so we don't have to scan all Quick components just to determine if there are any discriminated entities.

Then we set a discriminatorValue property on the child class, the value of which is stored in the parent entity table, which differentiates the different subclasses.

Then we set a discriminatorValue property on the child class, the value of which is stored in the parent entity table:

We aren’t entirely done yet. Finally, we must tell Quick whether we are using multi-table inheritance or single-table inheritance so it can map the database data to the subclass entities.

Multi-Table Inheritance (MTI)

If the data for your discriminated entities is normalized across multiple tables, you should use the multi-table inheritance (MTI) method for creating discriminated entities. In the example below, The Media entity has two subclasses, MediaBook and MediaAlbum. The discriminator column for the entities is the type column in the media table and the distinct properties for each subclass come from the media_book and media_album tables.

To inform Quick that our database schema follows the MTI pattern, we must add a joinColumn and table values for each subclass.

Single Table Inheritance (STI)

If the data for your discriminated entities lives in a single table, you should use the single-table inheritance (STI) method for creating discriminated entities. In the example below, the Media entity has two subclasses, MediaBook and MediaAlbum. The discriminator column for the entities is the type column in the media table, and the distinct properties for each subclass come from a single table.

To inform Quick that our database schema follows the STI pattern, we must also add singleTableInheritance=true to the parent entity.

Retrieving Discriminated Entities

Once the parent and child entities are defined, new BookMedia entities will be saved with a type value of "book" in the media table. As such, the following query will result in only entities of BookMedia being returned:

If our Media table contains a combination of non-book and book media, then the collection returned when querying all records will contain a mix of Media entities such as BookMedia and AlbumMedia

If you want to create a brand-new entity of a specific subclass, you can do so by calling newChildEntity( discriminatorValue ) like this:

Summary

Discriminated and child class entities, allow for a more Object oriented approach to entity-specific relationships by allowing you to eliminate pivot/join tables and extend the attributes of the base class.

To get started with Quick, you need an entity. You start by extending quick.models.BaseEntity.

That's all that is needed to get started with Quick. There are a few defaults of Quick worth mentioning here.

Tables

We don't need to tell Quick what table name to use for our entity. By default, Quick uses the pluralized, snake_cased name of the component for the table name. That means for our User entity Quick will assume the table name is users. For an entity with multiple words like PasswordResetToken the default table would be password_reset_tokens. You can override this by specifying a table metadata attribute on the component.

Inheritance

For more information on using inheritance and child tables in your relational database model, see .

Primary Key

By default, Quick assumes a primary key of id. The name of this key can be configured by setting variables._key in your component.

Quick also assumes a key type that is auto-incrementing. If you would like a different key type, override thekeyType function and return the desired key type from that function.

Quick ships with the following key types:

• AutoIncrementingKeyType

• NullKeyType

• ReturningKeyType

• UUIDKeyType

• RowIDKeyType

keyType can be any component that adheres to the keyType interface, so feel free to create your own and distribute them via ForgeBox.

Attributes

You specify what attributes are retrieved by adding properties to your component.

Now, only the id, username, and email attributes will be retrieved.

Persistent

To prevent Quick from mapping a property to a database column add the persistent="false" attribute to the property. This is needed mostly when using dependency injection.

Column

If the column name in your table is not the column name you wish to use in Quick, you can specify the column name using the column metadata attribute. The attribute will be available using the name of the attribute.

Null Values

To work around CFML's lack of null, you can use the nullValue and convertToNull attributes.

nullValue defines the value that is considered null for a attribute. By default it is an empty string. ("")

convertToNull is a flag that, when false, will not try to insert null in to the database. By default this flag is true.

Read Only

The readOnly attribute will prevent setters, updates, and inserts to a attribute when set to true.

SQL Type

In some cases you will need to specify an exact SQL type for your attribute. Any value set for the sqltype attribute will be used when inserting or updating the attribute in the database. It will also be used when you use the attribute in a where constraint.

Casts

The casts attribute allows you to use a value in your CFML code as a certain type while being a different type in the database. A common example of this is a boolean which is usually represented as a BIT in the database.

Two casters ship with Quick: BooleanCast@quick and JsonCast@quick. You can add them using those mappings to any applicable columns.

Custom Casts

The casts attribute must point to a WireBox mapping that resolves to a component that implements the quick.models.Casts.CastsAttribute interface. (The implements keyword is optional.) This component defines how to get a value from the database in to the casted value and how to set a casted value back to the database. Below is an example of the built-in BooleanCast, which comes bundled with Quick.

Casted values are lazily loaded and cached for the lifecycle of the component. Only cast values that have been loaded will have set called on them when persisting to the database.

Casts can be composed of multiple fields as well. Take this Address value object, for example:

This component is not a Quick entity. Instead it represents a combination of fields stored on our User entity:

Noticed that the casted address is neither persistent nor does it have a getter or setter created for it.

The last piece of the puzzle is our AddressCast component that handles casting the value to and from the native database values:

You can see that returning a struct of values from the set function assigns multiple attributes from a single cast.

Insert & Update

You can prevent inserting and updating a property by setting the insert or update attribute to false.

Formula, Computed, or Subselect properties

Multiple datasource support

Comparing Entities

You can compare entities using the isSameAs and isNotSameAs methods. Each method takes another entity and returns true if the two objects represent the same entity.

Once you have an entity and its associated database table you can start retrieving data from your database.

Active Record

You start every interaction with Quick with an instance of an entity. The easiest way to do this is using WireBox. getInstance is available in all handlers by default. WireBox can easily be injected in to any other class you need using inject="wirebox".

Quick is backed by qb, a CFML Query Builder. With this in mind, think of retrieving records for your entities like interacting with qb. For example:

In addition to using for you can utilize the each function on arrays. For example:

You can add constraints to the query just the same as you would using qb directly:

Quick Service

A second way to retrieve results is to use a Quick Service. It is similar to a VirtualEntityService from cborm.

The easiest way to create a Quick Service is to inject it using the quickService: dsl:

If you have a existing Service, and you would like to extend the quickService, you can extend the quikc.models.BaseService and then call super.init inside of the service init function passing the name of the entity (for example your User Entity) shown below:

Any method you can call on an entity can be called on the service. A new entity will be used for all calls to a Quick Service.

Aggregates

Calling qb's aggregate methods (count, max, etc.) will return the appropriate value instead of an entity or collection of entities.

existsOrFail

Returns true if any entities exist with the configured query. If no entities exist, it throws an EntityNotFound exception.

Retrieval Methods

all

Retrieves all the records for an entity. Calling all will ignore any non-global constraints on the query.

get

Executes the configured query, eager loads any relations, and returns the entities in a new collection.

paginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb pagination struct.

simplePaginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb simple pagination struct.

first

Executes the configured query and returns the first entity found. If no entity is found, returns null.

firstWhere

Adds a basic where clause to the query and returns the first result.

firstOrFail

Executes the configured query and returns the first entity found. If no entity is found, then an EntityNotFound exception is thrown with the given or default error message.

firstOrNew

Finds the first matching record or returns an unloaded new entity.

firstOrCreate

Finds the first matching record or creates a new entity.

find

Returns the entity with the id value as the primary key. If no record is found, it returns null instead.

findOrFail

Returns the entity with the id value as the primary key. If no record is found, it throws an EntityNotFound exception.

findOrNew

Returns the entity with the id value as the primary key. If no record is found, it returns a new unloaded entity.

findOrCreate

Returns the entity with the id value as the primary key. If no record is found, it returns a newly created entity.

newEntity

You will probably not use newEntity very often if you use wirebox getinstance("someQuickEntity") to retrieve an entity, because that will already give you a new entity. If you are using a QuickService you will need this method for creating a new entity

Hydration Methods

Hydration is a term to describe filling an entity with a struct of data and then marking it as loaded, without doing any database queries. For example, this might be useful when hydrating a user from session data instead of doing a query every request.

hydrate

Hyrdates an entity from a struct of data. Hydrating an entity fills the entity and then marks it as loaded.

If the entity's keys are not included in the struct of data, a MissingHydrationKey is thrown.

hydrateAll

Hydrates a new collection of entities from an array of structs.

Custom Collections

If you would like collections of entities to be returned as something besides an array, you can override the newCollection method. It receives the array of entities. You can return any custom collection you desire.

newCollection

Returns a new collection of the given entities. It is expected to override this method in your entity if you need to specify a different collection to return. You can also call this method with no arguments to get an empty collection.

delete

You can delete an entity by calling the delete method on it.

var user = getInstance( "User" ).find( 1 );
user.delete();

deleteAll

Just like updateAll, you can delete many records from the database by specifying a query with constraints and then calling the deleteAll method.

Deletes matching entities according to the configured query.

getInstance( "User" )
    .whereActive( false )
    .deleteAll();

Additionally, you can pass in an array of ids to deleteAll to delete only those ids. Note that any previously configured constraints will still apply.

getInstance( "User" ).deleteAll( [ 4, 10, 22 ] );

6.0.0

Dropped support for ColdBox 5

It's very likely that Quick v6 will still work on ColdBox 5, but it is no longer an officially supported platform.

5.1.0

KeyType now accepts the builder as a second argument to `preInsert`

This is only a breaking change if you have built your own key types. This is being released as a bug fix since the ReturningKeyType has not worked correctly since 5.0.0

/**
 * Called to handle any tasks before inserting into the database.
 * Receives the entity as the only argument.
 *
 * @entity   The entity that is being inserted.
 * @builder  The builder that is doing the inserting.
 *
 * @return   void
 */
public void function preInsert( required any entity, required any builder );

5.0.0

Dropped support for Adobe ColdFusion 2016

Please upgrade to a supported engine.

`addSubselect` calls must be accessed on the QuickBuilder

This means for scopes, you must call addSubselect off of the passed in builder object.

function scopeAddAuthorName( qb ) {
    qb.addSubselect( "authorName", "author.name" );
}

`applyGlobalScopes` functions now receive a Builder instance that should be used to call scopes

Instead of this:

function applyGlobalScopes() {
    this.addVendorName();
    this.addLocationName();
}

the scopes should be called on the passed in Builder instance:

function applyGlobalScopes( qb ) {
    qb.addVendorName();
    qb.addLocationName();
}

4.0.0

Scopes, whereHas, and whereDoesntHave are now automatically grouped when using an OR combinator

This isn't a breaking change that will affect most people. In fact, it will most likely improve your code.

Previously, when using scopes, whereHas, or whereDoesntHave, you were fully responsible for the wrapping of your where statements. For example, the following query:

var users = getInstance( "User" )
    .active()
    .search( event.getValue( "q", "" ) )
    .get();

with the following scopes defined:

function scopeActive( qb ) {
    qb.where( "active", 1 );
}

function scopeSearch( qb, term ) {
    qb.where( "username", "like", term & "%" )
        .orWhere( "email", "like", term & "%" );
}

would generate the following SQL:

SELECT *
FROM "users"
WHERE "active" = ?
    AND "username" = ?
    OR "email" = ?

The problem with this statement is that the OR can short circuit the active check.

The fix is to wrap the LIKE statements in parenthesis. This is done in qb using a function callback to where. Adding this nesting inside our scope will fix this problem.

function scopeSearch( qb, term ) {
    qb.where( function( q ) {
        q.where( "username", "like", term & "%" )
            .orWhere( "email", "like", term & "%" );
    } );
}

But this was easy to miss this. This is because you are in a completely different file than the built query. It also breaks the mental model of a scope as an encapsulated piece of SQL code.

In Quick 4.0.0, scopes, whereHas, and whereDoesntHave will automatically group added where clauses when needed. That means our original example now produces the SQL we probably expected.

SELECT *
FROM "users"
WHERE "active" = ?
    AND (
        "username" = ?
        OR "email" = ?
    )

Grouping is not needed if there is no OR combinator. In these cases no grouping is added.

var users = getInstance( "User" )
    .active()
    .isAdmin()
    .get();

function scopeActive( qb ) {
    qb.where( "active", 1 );
}

function scopeIsAdmin( qb ) {
    qb.where( "admin", 1 )
        .whereNotNull( "hireDate" );
}

SELECT *
FROM "users"
WHERE "active" = ?
    AND "admin" = ?
    AND "hireDate IS NOT NULL

If you had already wrapped your expression in a group inside the scope, whereHas, or whereDoesntHave call, nothing changes. Your code works as before. The OR combinator check only works on the top most level of added where clauses. Additionally, if you do not add any where clauses inside your scope, nothing changes.

The breaking change part is if you were relying on these statements residing at the same level without grouping. If so, you will need to group your changes into a single scope where you control the grouping or do the querying at the builder level outside of scopes.

3.0.0

Adobe ColdFusion 11 and Lucee 4.5 are no longer supported

Please migrate to a supported engine.

Virtual Inheritance support removed

Virtual Inheritance allowed you to use a quick annotation on your entity instead of extending quick.models.BaseEntity. This was hardly used and didn't offer any benefit to extending using traditional inheritance. Additionally, removing the support allows us to clean up the code base by removing duplicate code paths.

If any of your entities are using the quick annotation, instead have them extends="quick.models.BaseEntity".

`accessors="true"` required for all entities

From the early days of Quick, developers have wanted to have accessors="true" on their entities. Because of this, Quick supported defining entities both with and without accessors. However, just as with virtual inheritance, it created two code paths that could hide bugs and make it hard to follow the code. In Quick 3.0.0, accessors="true" is required on all entities. If it is omitted, a helpful error message is thrown to remind you. This will help immensely in simplifying the code base. (In fact, just introducing this requirement helped find two bugs that were only present when using accessors.)

Ensure all entities have accessors="true" in their component metadata.

AssignedKey removed

Use NullKeyType instead.

Boolean casts updates to hook in to new Cast system

Previously, the only valid cast type was casts="boolean". In introducing the new Casts system, the boolean cast was refactored to use the same system. For this reason, any casts="boolean" needs to be changed to casts="BooleanCast@quick"

defaultGrammar updated to be the full WireBox mapping

In previous versions, the value passed to defaultGrammar was used to look up a mapping in the @qb namespace. This made it difficult to add or use grammars that weren't part of qb. (You could get around this be registering your custom grammar in the @qb namespace, but doing so seemed strange.)

To migrate this code, change your defaultGrammar to be the full WireBox mapping in your moduleSettings:

moduleSettings = {
    "quick": {
        "defaultGrammar": "SqlServerGrammar@qb"
    }
};

HasManyThrough relationship re-tooled to be based on relationships

It no longer accepts any entities or columns. Rather, it accepts an array of relationships to walk "through" to end up at the desired entity.

Here's how the old syntax would be used to define the relationship between Country and Post.

component extends="quick.models.BaseEntity" {

    function posts() {
        return hasManyThrough( "Post", "User", "country_id", "user_id" );
    }

}

This same relationship now needs to be defined in terms of other relationships, like so.

component extends="quick.models.BaseEntity" {

    function posts() {
        return hasManyThrough( [ "users", "posts" ] );
    }

    function users() {
        return hasMany( "User" );
    }

}

component extends="quick.models.BaseEntity" {

    function posts() {
        return hasMany( "Post" );
    }

}

This approach does require a relationship defined for each level, but it works up and down any number of relationships to get to your desired entity.

`associate` cannot be called on unloaded entities

To update the foreign key of a belongsTo relationship you use the associate method. In the past, it was possible to associate a new, unsaved child entity to its parent using this method.

var newChild = getInstance( "Child" );
newChild.fill( fields );
newChild.parent().associate( parent );
newChild.save();

In an attempt to provide more helpful error messages, this behavior is no longer possible. You can achieve the same effect in one of two ways.

The first is to manually assign the foreign keys:

var newChild = getInstance( "Child" );
newChild.fill( fields );
newChild.setParentKey( parent.getId() );
newChild.save();

While this works, it breaks the encapsulation provided by the relationship.

The second approach is to use the hasOne or hasMany side of the relationship to create the new child entity:

var newChild = getInstance( "Child" );
newChild.fill( fields );
var parent = getInstance( "Parent" ).findOrFail( id );
parent.children().save( newChild );

If you have all the data handy in a struct, you can use the create method for a more concise syntax.

var parent = getInstance( "Parent" ).findOrFail( id );
var newChild = parent.children().create( fields );

This is the recommended way of creating these components.

assignAttributesData argument renamed to `attributes`

This brings the API in line with the other methods referencing attributes.

Method changes due to compound key support

Compound key support required some method and parameter name changes. Although the list seems extensive, you will likely not need to change anything in your code unless you have extended built-in Quick components. (You will see many relationship parameter name changes. Note that the function you call to define a relationship is a function on the BaseEntity and has not changed its signature.)

BaseEntity.cfc:

• retrieveQualifiedKeyName : String -> retrieveQualifiedKeyNames : [String]

• keyName : String -> keyNames : [String]

• keyColumn : String -> keyColumns : [String]

• keyValue : String -> keyValues : [String]

AutoIncrementingKeyType.cfc

• This cannot be used with composite primary keys

BaseRelationship.cfc

• getKeys now takes an array of keys as the second argument

• getQualifiedLocalKey : String -> getQualifiedLocalKeys : [String]

• getExistenceCompareKey : String -> getExistenceCompareKeys : [String]

BelongsTo.cfc

• init arguments have changed

  • foreignKey : String -> foreignKeys : [String]

  • localKey : String -> localKeys : [String]

• getQualifiedLocalKey : String -> getQualifiedLocalKeys : [String]

• getExistenceCompareKey : String -> getExistenceCompareKeys : [String]

BelongsToMany.cfc

• init arguments have changed

  • foreignPivotKey : String -> foreignPivotKeys : [String]

  • relatedPivotKey : String -> relatedPivotKeys : [String]

  • parentKey : String -> parentKeys : [String]

  • relatedKey : String -> relatedKeys : [String]

• getQualifiedRelatedPivotKeyName : String -> getQualifiedRelatedPivotKeyNames : [String]

• getQualifiedForeignPivotKeyName : String -> getQualifiedForeignPivotKeyNames : [String]

• getQualifiedForeignKeyName : String -> getQualifiedForeignKeyNames : [String]`