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 cfconfig.

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

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.

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

moduleSettings = {
    quick = {
        defaultGrammar = "MySQLGrammar"
    }
};

Valid options are any of the qb supported grammars. At the time of writing valid grammar options are: MySQLGrammar, PostgresGrammar, MSSQLGrammar and OracleGrammar. Please check the qb docs for additional options.

If you want to use a different datasource and/or grammar for individual entitities you can do so by adding some metadata attributes to your entities.

save

New Quick entities can be created and persisted to the database by creating a new entity instance, setting the attributes on the entity, and then calling the save method.

var user = getInstance( "User" );
user.setUsername( "JaneDoe" );
user.setEmail( "jane@example.com" );
user.setPassword( "mypass1234" );
user.save();

When we call save, the record is persisted from the database and the primary key is set to the auto-generated value (if any).

create

Another option is to use the create method. This method accepts a struct of data and creates a new instance with the data specified.

var user = getInstance( "User" ).create( {
    "username" = "JaneDoe",
    "email" = "jane@example.com",
    "password" = "mypass1234"
} );

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?

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

Supported Databases

Example

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

Prior Art, Acknowledgements, and Thanks

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

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 name of the component for the table name. That means for our User entity Quick will assume the table name is users. You can override this by specifying a table metadata attribute on the component.

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, define a function called `keyType` and return the key type from that function.

Quick ships with the following key types:

• AutoIncrementingKeyType

• NullKeyType

• ReturningKeyType

• UUIDKeyType

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

Columns

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

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

Note: Make sure to include the primary key (id by default) as a property.

To prevent Quick from mapping a property to the database add the persistent="false" attribute to the property.

If the column name in your table is not the column name you wish to use in quick, you can alias it using the column metadata attribute.

Multiple datasource support

delete

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

Note: The entity will still exist in any variables you have stored it in, even though it has been deleted from the database.

deleteAll

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

Additionally, you can pass in an array of ids to deleteAll to delete only those ids.

Definition

Query scopes are a way to encapsulate query constraints in your entities while giving them readable names .

A Practical Example

For instance, let's say that you need to write a report for subscribers to your site. Maybe you track subscribers in a users table with a boolean flag in a subscribed column. Additionally, you want to see the oldest subscribers first. You keep track of when a user subscribed in a