What's New?

11.2.0

Eager Loading

• Give entities a way to automatically eager load certain relationships.

• Allow preventing all lazy loading of relationships — very handy for quickly identifying N+1 problems.

Bug Fixes

• BoxLang compatibility updates

11.1.0

Add a GUID KeyType for use with guidqb column types.

Account for compound keys in hasManyDeep/hasManyThroughrelationships.

11.0.1

Fix for aliases with fully server qualified identifiers, like MyServer.schema.tableName.

11.0.0

• BoxLang Compatibility

• Pass grammar along to inferSqlType

10.0.1

Better matching of only "as" in relationship strings.

10.0.0

Upgrade to qb v10

9.0.3

Child Entities: Ensure single table inheritance columns are not duplicated.

9.0.2

HasOneThrough: Added the missing matchOnemethod.

Child Entities: Fixed qualifying columns on discriminated joined entities.

9.0.1

Fixed an issue with NULLvalues being inserted into identify columns for SQL Server

9.0.0

BREAKING CHANGES

• When eager loading a relationship, if there is a default entity defined, it will return the default entity instead of null.

• The hydrate function no longer accepts a ignoreNonExistentAttributes flag. This is because assignAttributesData always skips non-existent attributes.

Features

• Get a new filled instance of a relationship by calling the fill method on the relationship object.

• Add newAttributes and originalAttributes to the preUpdate event.

• Add firstOrNew, firstOrCreate, firstWhere, findOrNew, and findOrCreate methods to Relationship classes.

• Allow specifying virtual attributes with a cast.

• Allow returning a new non-persisted entity from a relationship using the newEntity function.

Bug Fixes

• Clear the relationship cache for a relationship when using the relationship setter.

• Only compute the attributes hash from persistent attributes.

• Handle null values when assigning to attributes

• Fixed an issue where virtual attributes were not being applied to discriminated child entities when loading through the parent.

8.0.3

Respect qb's SQL Commenter support options.

8.0.2

Handle skipping constraints when a relationship is defined with other relationships

8.0.1

Make the withoutRelationshipConstraints check more resilient by checking against a set of relationship method names.

8.0.0

BREAKING CHANGE

The withoutRelationshipConstraints method now requires the relationship method name as the first parameter.

This is used to ensure only the desired relationship has its constraints skipped. This is especially important in asynchronous contexts.

7.4.4

Fix for thread safety when loading multiple relationships off of a single entity

7.4.3

Fix qualifying column issue when using HasManyDeep relationships.

7.4.2

Remove duplicate join from addCompareConstraints when using HasManyDeep relationships.

7.4.1

Upgrade to latest str dependency

7.4.0

HasManyDeep

Introduced a new alternative relationship to the old hasManyThrough — hasManyDeep. It produces more readable, parsable SQL and is the basis for the new version of hasManyThrough.

HasManyDeepBuilder

If you prefer the hasManyDeep syntax over the hasManyThrough syntax, you might enjoy the HasManyDeepBuilder, a builder object to create the hasManyDeep relationship. It is generally more readable, especially when using additional constraints on related or through entities, at the cost of verbosity.

Revamped HasManyThrough relationships

All hasManyThrough relationships are now hasManyDeep relationships under the hood. No code changes should be necessary for you to enjoy more readable SQL, less bugs, and greater performance. 🏎️

7.3.2

Use the interceptor approach instead of wirebox:targetId to support CommandBox 5.

7.3.1

Fix where discriminated entities could use the wrong qualified column name in the join with the parent entity.

7.3.0

New Features

• Return optional QuickBuilder instances for withCount and withSum to allow for further chaining.

Bug Fixes

• Fix clearAttribute when not setting to null.

• Fix using a QueryBuilder instance to define a subselect.

Additional Test Cases

• Add test case for checking null attributes on newly created entities.

• Add test case for deleteAll off of a hasMany relationship.

• Add test case for belongsToMany withCount.

• Add test case for firstOrNew with aliases and columns.

7.2.0

Allow setting defaultOptions for the underlying qb instance backing Quick.

7.1.1

Pin commandbox-semantic-release to version 3.

7.1.0

Add a withSum method, similar to withCount for quickly adding a subselect based on the sum of a relationship's attribute.

7.0.1

Correctly handle null values with casted attributes.

7.0.0

QuickBuilder now has its own clone method that behaves as you would expect. Previously, it only cloned the enclosed QueryBuilder which was not that useful.

Making this fix required the newQuery method of QuickBuilder to return an instance of QuickBuilder instead of QueryBuilder as it previously was. If you need a new QueryBuilder instance from a QuickBuilder, use the newQuickQB method.

6.2.1

Allow a QuickBuilder to be used wherever a QueryBuilder can be used.

6.2.0

Add the ability to exclude all global scopes at once.

6.1.0

Introducing the asQuery method

This method is similar to asMemento. You use it when the return format you want is an array of structs. asQuery will skip creating entities at all, instead returning the values straight from qb. This can result in a large performance boost depending on the number of records being returned. Additionally, asQuery supports returning the columns using the alias names and returning eager loaded entities.

Read more in the asQuery docs.

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:

Engine	4.2.0	5.0.0
adobe@2018	7.65 ms	3.71 ms
adobe@2021	6.68 ms	2.10 ms
lucee@5	3.94 ms	0.88 ms

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

📹 Watch a walkthrough of these changes on CFCasts.

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+