> For the complete documentation index, see [llms.txt](https://qb.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qb.ortusbooks.com/14.0.0/installation-and-usage.md).

# Installation & Usage

## Installation

Installation is easy through [CommandBox](https://www.ortussolutions.com/products/commandbox) and [ForgeBox](https://www.forgebox.io/). 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`.

```cfscript
moduleSettings = {
    qb = {
        defaultGrammar = "MySQLGrammar@qb"
    }
};
```

The grammars provided by qb are:

* MySQLGrammar
* OracleGrammar
* PostgresGrammar
* SqlServerGrammar
* SQLiteGrammar
* DerbyGrammar

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

```cfscript
var grammar = new qb.models.Grammars.MySQLGrammar();
var builder = new qb.models.Query.QueryBuilder( grammar );
```

## Configuration Settings

Here are the full configuration settings you can use in the module settings:

```javascript
moduleSettings = {

    qb : {
        "defaultGrammar": "AutoDiscover@qb",
        "defaultReturnFormat": "array",
        "preventDuplicateJoins": false,
        "validateOperatorsAndCombinators": true,
        "validateDuplicateSelectColumns": false,
        "validateQueryExecuteReturnType": false,
        "collectQueryLog": true,
        "convertEmptyStringsToNull": true,
        "shouldWrapValues": true,
        "validateQueryParamStructKeys": true,
        "integerSQLType": "INTEGER",
        "bigIntegerSQLType": "BIGINT",
        "decimalSQLType": "DECIMAL",
        "defaultOptions": {},
        "sqlCommenter": {
            "enabled": false,
            "commenters": [
                { "class": "FrameworkCommenter@qb", "properties": {} },
                { "class": "RouteInfoCommenter@qb", "properties": {} },
                { "class": "DBInfoCommenter@qb", "properties": {} }
            ]
        },
        "shouldMaxRowsOverrideToAll": function( maxRows ) {
            return maxRows <= 0;
        },
        "returnFormatters": {}
    }

}
```

`validateOperatorsAndCombinators` validates operators and boolean combinators before compiling a query. It defaults to `true`. Disable it only when an application intentionally uses database-specific operators or combinators that qb does not recognize.

`collectQueryLog` controls whether a QueryBuilder appends execution details to its [query log](/14.0.0/query-builder/debugging.md#querylog). It defaults to `true`. Set it to `false` when query-log collection is not needed.

`validateQueryParamStructKeys` validates custom query parameter structs against the supported `cfqueryparam` keys. It defaults to `true`. Disabling it restores the earlier behavior of ignoring unknown keys.

`validateDuplicateSelectColumns` detects statically identifiable duplicate output names when a query is compiled. It is useful in development and is disabled by default to avoid production overhead. See [Duplicate Select Column Validation](/14.0.0/query-builder/building-queries/selects.md#duplicate-select-column-validation).

`validateQueryExecuteReturnType` throws when native `queryExecute` return-type options are passed to qb. It is useful while migrating an application to [named return formatters](/14.0.0/query-builder/options-and-utilities/return-format.md#native-queryexecute-return-types).

`shouldWrapValues` controls identifier wrapping for the configured grammar. It defaults to `true`. Set it to `false` to generate unwrapped identifiers by default; individual queries can override it with [`withWrappingValues`](/14.0.0/query-builder/options-and-utilities/query-options.md#withwrappingvalues) and [`withoutWrappingValues`](/14.0.0/query-builder/options-and-utilities/query-options.md#withoutwrappingvalues).

`returnFormatters` registers reusable named formatter factories. See [Custom Return Formatters](/14.0.0/query-builder/options-and-utilities/return-format.md#custom-return-formatters).

## SQL Type Inference

qb binds parameters by default and infers a SQL type from each value. Numeric values use separate configurable types:

| Value                                                 | Setting             | Default   |
| ----------------------------------------------------- | ------------------- | --------- |
| Whole numbers from `-2147483648` through `2147483647` | `integerSQLType`    | `INTEGER` |
| Whole numbers outside the signed 32-bit range         | `bigIntegerSQLType` | `BIGINT`  |
| Numbers with a decimal portion                        | `decimalSQLType`    | `DECIMAL` |

The boundary values are included in the `INTEGER` range. Values below `-2147483648` or above `2147483647` use `BIGINT`.

Override these defaults in `config/ColdBox.cfc` when your database or schema requires different types:

```cfscript
moduleSettings = {
    qb = {
        defaultGrammar = "MySQLGrammar@qb",
        integerSQLType = "INTEGER",
        bigIntegerSQLType = "BIGINT",
        decimalSQLType = "DECIMAL"
    }
};
```

You can always bypass inference for an individual value by passing a [custom query parameter](/14.0.0/query-builder/building-queries/parameters-and-bindings.md#custom-parameter-types) with an explicit `cfsqltype`.

## 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`.

```cfscript
this.mappings = {
    "/qb" = expandPath("./subsystems/qb")
};
```

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.

```cfscript
qb = {
  diLocations = "/qb/models",
  diConfig = {
    loadListener = function( di1 ) {
      di1.declare( "BaseGrammar" ).instanceOf( "qb.models.Query.Grammars.Grammar" ).done()
         .declare( "MySQLGrammar" ).instanceOf( "qb.models.Query.Grammars.MySQLGrammar" ).done()
         .declare( "QueryUtils" ).instanceOf( "qb.models.Query.QueryUtils" ).done()
         .declare( "QueryBuilder" ).instanceOf( "qb.models.Query.QueryBuilder" )
         .withOverrides({
            grammar = di1.getBean( "MySQLGrammar" ),
            utils = di1.getBean( "QueryUtils" ),
            returnFormat = "array"
         })
         .asTransient();
    }
  }
}
```

### 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()`.

```cfscript
// Create an instance of qb
builder = getBeanFactory( "qb" ).getBean( "QueryBuilder" );
// Query the database
posts = builder.from( "Posts" ).get();
posts = builder.from( "Posts" ).where( "IsDraft", "=", 0 ).get();
```

#### For further instructions on getting started with qb & FW/1, refer to [this blog post](http://tonyjunkes.com/blog/working-with-fw1-and-qb/).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://qb.ortusbooks.com/14.0.0/installation-and-usage.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.