8.1.0

• orderByRaw now can accept bindings.

• A new, optional strictDateDetection setting is available to check the underlying Java class of a date object instead of using isDate.

8.0.3

• Ignore select bindings for aggregate queries.

• Allow spaces in table aliases.

• Split FLOAT and DECIMAL column types in SQL Server.

8.0.2

• Clear orderBy bindings when calling clearOrders.

8.0.1

• Trim table definitions before searching for aliases. Makes qb more lenient with extra whitespace.

8.0.0

BREAKING CHANGES

• when callbacks now automatically scope and group where clauses when an OR combinator is used.

Other Changes

• Combine clearOrders and orderBy with a new reordermethod.

• Clear current selected columns with clearSelect.

• Combine clearSelect and either select or selectRaw with reselect and reselectRaw respectively.

7.10.0

• Expose nested where functions to enable advanced query manipulation in downstream libraries like Quick.

7.9.9

• Fixes for OracleGrammar including table aliases and wrapped subqueries.

7.9.8

• Allow nullable timestamps in MySQL.

7.9.7

• Return 0 on null aggregates.

7.9.6

• Match type hints to documentation for join functions

7.9.5

• Handle enhanced numeric checks with Secure Profile enabled.

7.9.4

• Allow raw statements in basic where clauses.

7.9.3

• Passed along the options struct to the count method when calling paginate.

7.9.2

• Allow for space-delimited sort directions like column DESC.

• Add helpful message when trying to use a closure with from instead of fromSub.

• value and values now work with column formatters.

• Correctly format RETURNING clauses with column formatters and ignoring table qualifiers.

7.9.1

• Handle multi-word columns in queryRemoveColumns.

7.9.0

• Remove elvis operator due to ACF compatibility issues

7.8.0

• Add support for MONEY and SMALLMONEY data types to SchemaBuilder.

7.7.3

• Fix wrapping of enum types for Postgres.

7.7.2

• Compatibility fix for ACF 2018 and listLast parsing.

• Include current_timestamp default for timestamp columns in SchemaBuilder.

• Ignore table qualifiers for insert and update.

7.7.1

• Fix a bug with preventDuplicateJoins when using the closure syntax with a join.

7.7.0

• Add executionTime to the data output from BaseGrammar, including being available in interceptors.

7.6.2

• Fix a case where a column was not wrapped correctly when a where used a subquery for the value.

7.6.1

• Avoid duplicate function due to cbORM / Hibernate bugs when used in the same application.

7.6.0

• Split off a private whereBasic method. This is used in Quick to provide extra sql type features.

• Add a clearOrders method. Any already configured orders are cleared. Any orders added after this call will be added as normal.

• selectRaw now can take an array of expressions.

7.5.1

Fixed an issue using column formatters with update and insert.

7.5.0

Using a new preventDuplicateJoins setting in the module settings, qb can detect duplicate joins and ignore them. This is especially useful in a heavily filtered and dynamic query where you may or may not need the join at all or more than one column may need the same join. preventDuplicateJoins defaults to false, so it is opt-in. It may be turned on by default in a future breaking release of qb.

7.4.0

Enhance order by's with more direction options (c767ac8)

You can now use two shortcut methods: orderByAsc and orderByDesc. Additionally, orderBySub or using orderBy with a closure or builder instance will respect the direction argument.

7.3.15

• Fix using whereBetween with query param structs (07c9b72)

7.3.14

• Ignore orders in aggregate queries (39e1338)

7.3.13

• Format with cfformat (dc2a9b6)

7.3.12

• Improve column wrapping with trimming (d98a5cb)

• Prefer the parent query over magic methods when the parent query has the exact method. (f9fd8d1)

7.3.9, 7.3.10, 7.3.11

• Switch to using ForgeBox Storage.

7.3.8

• Allow passing query options in to paginate (cdecfb3)

7.3.7

• Fix for inserting null values directly (1de27a6)

7.3.5, 7.3.6

• Use cfformat for automatic formatting (119e434)

• Add a type to the onMissingMethod exception (90d1093)

7.3.4

• Correctly wrap comments in MySQLGrammar.

7.3.2, 7.3.3

• Publish qb apidocs to Ortus API Docs.

7.3.1

• Fix for null values breaking the new checkIsActuallyNumeric method in QueryUtils.

7.3.0

• Add a parameterLimit public property to SqlServerGrammar. This property is used in Quick to split up eager loading to work around the 2100 param limit of SQL Server.

7.2.0

• Allow a parent query to be set. A parent query will receive any method calls that are not found on the Query Builder instance. This is especially useful for instances like Quick to allow Quick features like scopes to be available inside any closures.

7.1.0

• Lambdas (arrow functions) are now allowed wherever closures are allowed.

• Add an orderByRaw method.

• Allow for fully-qualified column names (table_name.column.name) in the value and values methods.

7.0.0

BREAKING CHANGES

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

• Drop support for Lucee 4.5 and Adobe ColdFusion 11.

• MSSQLGrammar renamed to SqlServerGrammar

• Remove variadic parameters support in builder functions like select.

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

• The argument names of forPage changed to match the new paginate method.

• Add defaultValue and optional exception throwing to value. (This changed the argument order.)

• All methods that could conceivably take a subquery as well as a value now accept a closure or another builder instance to use as a subquery. (This changed the argument names in some instances.)

Other Changes

• Completely revamped documentation! (You're looking at it right now.)

• Add new flag to toSQL( showBindings = true ) to replace question marks (?) with cfqueryparam-compatible structs for debugging.

• Preserve column case and order when converting a query to an array using the default "array" return format.

• Add a new paginate method to generate a pagination struct alongside the results. This can be customized using a custom PaginationCollector.

• Allow raw values in insert calls.

• Allow default queryExecute options to be configure at a Query Builder level. This also enables custom QueryBuilders a la Hyper.

• Add a whereLike method.

• Allow closures to be used in left and right joins.

• Provide an addUpdate method to programmatically build the SET clause of an update query.

• Add a new chunk method to grab records from the database in small sets.

• Add raw in alterTable segments.

• Add dropAllObjects support for SqlServerGrammar and OracleGrammar to support migrate fresh from cfmigrations.

• Add a renameTable alias for rename.

• Remove default constraints when dropping columns with a default on SqlServerGrammar.

• Add more column types and column helpers to SchemaBuilder, including:

  • datetimeTz

  • lineString

  • nullableTimestamps

  • point

  • polygon

  • softDeletes

  • softDeletesTz

  • timeTz

  • timestamps

  • timestampTz

  • timestampsTz

  • withCurrent

6.4.0

• Allow Expressions (query.raw) in update statements.

We welcome all types of contributions!

The most common type of contribution is to fix an incorrect SQL generation for a database grammar.

To debug what SQL is being ran, you can always call toSQL on any QueryBuilder or SchemaBuilder object. Additionally, you can listen to the preQBExecute interception point for the generated SQL.

Each of the database grammars have two tests — {Grammar}QueryBuilderSpec.cfc and {Grammar}SchemaBuilderSpec.cfc. These tests run the same qb syntax across the different grammars. In each test are methods that return SQL strings like so:

// MSSQLQueryBuilderSpec.cfc
function orWhere() {
    // If just a string is returned, we assume the bindings is an empty array ([])
    return {
        sql = "SELECT * FROM [users] WHERE [id] = ? OR [email] = ?",
        bindings = [ 1, "foo" ]
    };
}

// OracleSchemaBuilderSpec.cfc
function boolean() {
    // returns an array since schema builder can execute multiple statements.
    return [ "CREATE TABLE ""USERS"" (""ACTIVE"" NUMBER(1, 0) NOT NULL)" ];
}

If you find an issue with the SQL generated from a grammar, please file a pull request with the correct SQL in these tests. It's okay if you don't submit a fix as well. (But we'd greatly appreciate it!) Doing so will help expedite the fix.

If you want to add support for a new database grammar, simply copy these two tests from an existing grammar, rename them, change the getBuilder method to return your new grammar, and fill out the SQL as it should be. That will guide your implementation to be 100% compatible with the other grammars in qb.

from

Used to set the base table for the query.

query.from( "users" );

SELECT * FROM `users`

You can optionally specify an alias for the table.

query.from( "users as u" );

SELECT * FROM `users` AS `u`

table

An alias for from where you like how calling table looks.

query.table( "users" ).insert( { "name" = "jon" } );

INSERT INTO `users` (`name`) VALUES (?)

fromRaw

Sometimes you need more control over your from clause in order to add grammar specific instructions, such as adding SQL Server table hints to your queries.

query.fromRaw( "[users] u (nolock)" ).get();

SELECT * FROM [users] u (nolock) 

Since the fromRaw() takes your string verbatim, it's important that you make sure your SQL declaration is escaped properly. Failure to properly escape your table names may result in SQL errors.

Many database engines allow you to define User Defined Functions. For example, SQL Server allows you to define UDFs that will return a table. In these type of cases, it may be necessary to bind parameters to your from clause.

You can bind parameters to the fromRaw() method by passing a secondary argument that is an array of the parameters to bind.

query.fromRaw(
    "dbo.generateDateTable(?, ?, ?) as dt",
    [ "2017-01-01", "2017-12-31", "m" ]
).get();

SELECT * FROM dbo.generateDateTable(?, ?, ?) as dt

fromSub

Complex queries often contain derived tables. Derived tables are essentially a temporal table defined as a subquery in the from statement.

query.select( [ "firstName", "lastName" ] )
    .fromSub( "legalUsers", function ( q ) {
        q.select( [ "lName as lastName", "fName as firstName" ] )
            .from( "users" )
            .where( "age", ">=", 21 )
        ;
    } )
    .orderBy( "lastName" )
    .get()

SELECT `firstName`, `lastName`
FROM (
    SELECT `lName` as `lastName`, `fName` as `firstName`
    FROM `users`
    WHERE `age` >= 21
) AS `legalUsers`
ORDER BY `lastName`

In additional a function callback, a separate QueryBuilder instance can be passed to the fromSub method.

var legalUsersQuery = query
    .select( [ "lName as lastName", "fName as firstName" ] )
    .from( "users" )
    .where( "age", ">=", 21 );

query.select( [ "firstName", "lastName" ] )
    .fromSub( "legalUsers", legalUsersQuery )
    .orderBy( "lastName" )
    .get();

SELECT `firstName`, `lastName`
FROM (
    SELECT `lName` as `lastName`, `fName` as `firstName`
    FROM `users`
    WHERE `age` >= 21
) AS `legalUsers`
ORDER BY `lastName`

Introduction

Using qb, you can:

• Quickly scaffold simple queries

• Make complex, out-of-order queries possible

• Abstract away differences between database engines

Requirements

• Adobe ColdFusion 2016+

• Lucee 5+

qb supports four major database grammars:

• MySQL (MySQLGrammar)

• Oracle (OracleGrammar)

• Postgres (PostgresGrammar)

• Microsoft SQL Server (SqlServerGrammar)

Installation

Code Samples

Compare these two examples:

The differences become even more stark when we introduce more complexity:

With qb you can easily handle setting order by statements before the columns you want or join statements after a where clause:

qb enables you to explore new ways of organizing your code by letting you pass around a query builder object that will compile down to the right SQL without you having to keep track of the order, whitespace, or other SQL gotchas!

Usage

To start a new query, instantiate a new Builder: wirebox.getInstance('QueryBuilder@qb').

By default, qb uses a generic Grammar. You can specify your specific grammar in ColdBox by setting the defaultGrammar in your moduleSettings.

If you are not using WireBox, just make sure to wire up the Builder object with the correct grammar:

Join clauses range from simple to complex including joining complete subqueries on multiple conditions. qb has your back with all of these use cases.

join

Applies a join to the query. The simplest join is to a table based on two columns:

When doing a simple join using = as the operator, you can omit it and pass just the column names:

When you need to specify more clauses to join, you can pass a function as the second argument:

Conditions inside a join clause can be grouped using a function.

joinWhere

Adds a join to another table based on a WHERE clause instead of an ON clause. WHERE clauses introduce parameters and parameter bindings whereas on clauses join between columns and don't need parameter bindings.

For simple joins, this specifies a column on which to join the two tables:

joinRaw

joinSub

Alternatively, a function may be used to define the derived table:

Complex join conditions are also possible by passing a function as the third parameter:

leftJoin

leftJoinRaw

leftJoinSub

rightJoin

rightJoinRaw

rightJoinSub

crossJoin

crossJoinRaw

Uses the raw SQL provided to as the table for the cross join clause. Cross joins cannot be further constrained with on or where clauses.

crossJoinSub

newJoin

JoinClause

on

Applies a join condition to the JoinClause. An alias for whereColumn.

orOn

Applies a join condition to the JoinClause using an or combinator. An alias for orWhereColumn.

Preventing Duplicate Joins

You can optionally configure qb to ignore duplicate joins. With this setting turned on each JoinClause is inspected and checked if it matches any existing JoinClause instances on the query. This is useful if you have a table shared between optional constraints and want to ensure it is only added once.

You can opt-in to this behavior by setting preventDuplicateJoins = true in your moduleSettings in config/ColdBox.cfc.

A query builder is a stateful, transient object. That means that if you want to execute two different queries, you need two separate instances of QueryBuilder.

As such, be careful when injecting QueryBuilder in to a component. If the component is a singleton, you will need to create the QueryBuilder inline or use a provider. This applies to ColdBox handlers as well.

While the above may seem innoculous, it can run in to issues as multiple requests come in to your application. Each request is sharing the same query builder instance and subsequent requests will have unintended results as the where clause keeps growing request after request.

The solution is to either create the QueryBuilder inline, ensuring that each request has its own query to execute:

Or to use a WireBox provider to create a new query each time it is accessed:

newQuery

Once you have access to a QueryBuilder instance, you can create a new query using the same datasource, utils, returnFormat, paginationCollector, columnFormatter, and defaultOptions as the current QueryBuilder instance.

The orderBy method seems simple but has a lot of depth depending on the type of arguments you pass in.

Order By (String)

Calling orderBy multiple times will append to the order list.

Order By (List)

Order By (Array of Strings)

Order By (Array of Structs)

Order By (Subquery)

You can order with a subquery using either a function or a QueryBuilder instance.

Order By Raw

clearOrders

reorder

Where Methods

where

Adds a where clause to a query.

Any of the following operators can be used in a where clause.

When using the "=" constraint, you can use a shortcut and define the value as the second argument.

To group where statements together, pass a function to the where clause as the only parameter.

A Function or QueryBuilder can be used as a subselect expression when passed to value.

andWhere

orWhere

whereBetween

Adds a where between clause to the query.

If a function or QueryBuilder is passed it is used as a subselect expression.

whereNotBetween

whereColumn

Adds a where clause to a query that compares two columns.

Just as with where, when using "=" as the operator you can use a shorthand passing the second column in as the operator and leaving the second column null.

Expressions can be passed in place of either column.

whereExists

Adds a where exists clause to the query.

It can be configured with a function.

It can also be configured with a QueryBuilder instance.

whereNotExists

whereLike

whereIn

Adds a where in clause to the query.

The values passed to whereIn can be a single value, a list of values, or an array of values.

If a list of values is passed in, it is converted to an array of values using a single comma (",") delimiter.

Expressions can be freely mixed in with other values.

A function or QueryBuilder instance can be passed to be used as a subquery expression instead of a list of values.

whereNotIn

whereRaw

Shorthand to add a raw SQL statement to the where clauses.

whereNull

Adds a where null clause to the query.

whereNotNull

Dynamic Where Methods

qb uses onMissingMethod to provide a few different helpers when working with where... methods.

andWhere... and orWhere...

Every where... method in qb can be called prefixed with either and or or. Doing so will call the original method using the corresponding combinator.

where{Column}

If you call a method starting with where that does not match an existing qb method, qb will instead call the where method using the rest of the method name as the first column name. (The rest of the arguments will be shifted to account for this.) This also applies to andWhere{Column} and orWhere{Column} method signatures.

Installation

Installation is easy through and . Simply type box install qb to get started.

Usage

To start a new query, instantiate a new Builder: wirebox.getInstance('QueryBuilder@qb').

By default, qb uses a generic Grammar. You can specify your specific grammar in ColdBox by setting the defaultGrammar in your moduleSettings.

The grammars provided by qb are:

• MySQLGrammar

• OracleGrammar

• PostgresGrammar

• SqlServerGrammar

If you are not using WireBox, just make sure to wire up the Builder object with the correct grammar:

Integrating With FW/1

Note: These instructions assume a basic knowledge of FW/1, a working FW/1 application structure with qb installed in the /subsystems directory (manually or via CommandBox), and a database configured to run with your application.

Wiring Up With DI/1

Once the application structure is setup, now we need to wire up qb to a bean factory using DI/1.

First we will add a mapping in Application.cfc.

Next we need to tell DI/1 where qb's components are and how to reference them for later use in the application. We can do so by defining the configuration settings in the variables.framework.subsystems struct in Application.cfc. The example below makes use of a load listener to declare each component instance and pass in any constructor arguments.

Usage In Your FW/1 Application

Now that everything is configured, you can launch your application with CommandBox by entering start in the terminal or use whatever method you're accustomed to.

To access qb from your application's code, you can call on it by using getBeanFactory().

limit

Sets the limit value for the query.

take

Sets the limit value for the query. Alias for .

offset

Sets the offset value for the query.

forPage

Helper method to calculate the limit and offset given a page number and count per page.

paginate

groupBy

Passing a single string will group by that one column.

You can also pass a list of column names. A single comma (",") will be used as the delimiter.

An array of column names can be provided.

Calling groupBy multiple times will to the current groups.

having

Adds a having clause to a query.

Expressions can be used in place of the column or the value.

If you store the builder object in a variable, you can use if and else statements like you would expect.

This works, but breaks chainability. To keep chainability you can use the when helper method.

when

The when helper is used to allow conditional statements when defining queries without using if statements and having to store temporary variables.

You can pass a third argument to be called in the else case.

when callbacks are automatically scoped and grouped. That means that if a where clause is added inside the callback with an OR combinator the clauses will automatically be grouped (have parenthesis put around them.) You can disable this feature by passing withoutScoping = true to the when callback.