Squel.js

- lightweight Javascript library for building SQL query strings.

- usable with node.js and in the browser.

- well tested.

npm install squel

Basic version

(~6.4 KB minified + gzipped)

Basic + Database engines

(~7.3 KB minified + gzipped)

Installation

Node.js

npm install squel

Once done you can use require to access the API:

var squel = require("squel");

Bower

bower install squel

Browser

Include the following within your HTML body section, near the bottom:

<script type="text/javascript" src="/your/path/to/squel.min.js"></script>

Once loaded the squel API will be available in the global object:

alert( squel.VERSION );    // version string

NOTE: It is recommended that you do NOT create queries browser-side to run on the server as this massively increases your exposure to SQL Injection attacks.

Overview

Squel helps you quickly and easily build SQL query strings through an object oriented API. There are two main benefits to using Squel to build your queries:

  1. It requires less effort - instead of having to use brittle methods like string concatenation and substitution you get a nice clean API to do the hard work for you.
  2. It lets you build flexibly - Sometimes you don't yet know what your final query ought to look like until you've checked information from various other parts of your program. Representing the query as an object which can be manipulated allows you to be flexible about how you build it.

Ok, now you're convinced! Before you get stuck in here are a few things to be aware of...

Squel uses method chaining to make things easy. For example, instead of writing:

            var s = squel.select();
            s.from("student");
            alert( s.toString() );    /* SELECT * FROM student */
        

Hint: You can run the example above by clicking it!

You can simply write:

            alert( squel.select().from("students").toString() );  // SELECT * FROM students
        
What's even better, the toString() method gets called automatically by the Javascript interpreter whenever a string representation of an object is needed. So we can actually simplify the previous statement to:
            alert( squel.select().from("students") );  /* SELECT * FROM students */
        

Note: All of Squel's builders provide the toString() method. It is this method which constructs the final query string.

Squel does not check to see if your final query is semantically correct (i.e. that it makes sense). Your database engine already does a good enough job of that. On the plus side Squel allows you to use proprietary database functions and other complex constructs:

            alert(
                squel.select()
                    .from("students")
                    .field("name")
                    .field("MIN(test_score)")
                    .field("MAX(test_score)")
                    .field("GROUP_CONCAT(DISTINCT test_score ORDER BY test_score DESC SEPARATOR ' ')")
                    .group("name")
            );
            /*
                SELECT
                    name,
                    MIN(test_score),
                    MAX(test_score),
                    GROUP_CONCAT(DISTINCT test_score ORDER BY test_score DESC SEPARATOR ' ')
                FROM
                    students
                GROUP BY
                    name
            */
        

Note: Unless stated otherwise all query builder methods require string arguments. Passing in objects, arrays or functions will result in exceptions being thrown.

SELECT

To get an instance of the SELECT query builder:

            var q = squel.select();
        

Calling toString() on it now will throw an exception:

            try {
                alert( squel.select() );  /* remember that toString() is implicitly called here */
            } catch (error) {
                alert( error ); /* from() needs to be called */
            }
        

Thus, at a minimum the name of a table to fetch data from must be provided:

            alert(
                squel.select()
                    .from("students")
            );
            /* SELECT * FROM students */
        

Squel usually outputs a single line string, but you can use a different separator to change this look:

            alert(
                squel.select({ separator: "\n" })
                    .from("students")
            );
            /*
                SELECT
                * 
                FROM students
            */
        

Multiple tables

You can select data from multiple tables and provide aliases where needed:

            alert(
                squel.select()
                    .from("students")
                    .from("lecturers", "l")
                    .from("admins")
            );
            /* SELECT * FROM students, lecturers `l`, admins */
        

Sub-queries as tables

Instead of explicitly naming tables you can use SQL sub-queries as such:

            alert(
                squel.select()
                    .from( squel.select().from('students'), 's' )
                    .field('s.id')
            );
            /*  SELECT s.id FROM (SELECT * FROM students) `s` */
        

Fields

You can specify field names on their own or by the table they belong to:

            alert(
                squel.select()
                    .from("students")
                    .field("id")
                    .field("students.name")
            );
            /* SELECT id, students.name FROM students */
        

Field names can be given aliases in order to customize the column names in the query results :

            alert(
                squel.select()
                    .from("students")
                    .field("id", "Id")
                    .field("students.name", "Student Name")
            );
            /* SELECT id AS "Id", students.name AS "Student Name" FROM students */
        

Database functions can be used in place of field names for more complex results:

            alert(
                squel.select()
                    .from("students", "s")
                    .field("s.id")
                    .field("s.test_score", "Test score")
                    .field("DATE_FORMAT(s.date_taken, '%M %Y')", "Taken on")
            );
            /*
                SELECT
                    s.id,
                    s.test_score AS "Test score"
                    DATE_FORMAT(s.date_taken, '%M %Y') AS "Taken on"
                FROM
                    students `s`
            */
        

You can even use a sub-query as a field specifier:

            alert(
                squel.select()
                    .from("students", "s")
                    .field(squel.select().field("MAX(score)").from("scores"), 'score')
            );
            /*
                SELECT
                    (SELECT MAX(score) FROM scores) AS "score"
                FROM
                    students `s`
            */
        

If you wish to obtain DISTINCT results you can do so:

            alert(
                squel.select()
                    .from("students")
                    .field("id")
                    .distinct()
            );
            /*  SELECT DISTINCT id FROM students    */
        

Joins

Squel supports INNER, OUTER, LEFT and RIGHT joins. To do an INNER join:

            alert(
                squel.select()
                    .from("students")
                    .join("teachers")
            );
            /*  SELECT * FROM students INNER JOIN teachers */
        

You can specify table aliases:

            alert(
                squel.select()
                    .from("students")
                    .join("teachers", "t")
                    .outer_join("expelled")
            );
            /*  SELECT * FROM students
                    INNER JOIN teachers `t`
                    OUTER JOIN expelled
            */
        

You can specify sub-queries:

            alert(
                squel.select()
                    .from("students")
                    .join(
                        squel.select().field('score').from('results'),
                        't'
                    )
                    .outer_join("expelled")
            );
            /*  SELECT * FROM students
                    INNER JOIN (SELECT score FROM results) `t`
                    OUTER JOIN expelled
            */
        

And you can specify JOIN-ing conditions:

            alert(
                squel.select()
                    .field("students.id")
                    .from("students")
                    .left_join("teachers", null, "students.id = teachers.student_id")
                    .right_join("jailed", "j", "j.student_id = students.id")
            );
            /*  SELECT students.id FROM students
                    LEFT JOIN teachers ON (students.id = teachers.student_id)
                    RIGHT JOIN jailed `j` ON (j.student_id = students.id)
            */
        

For an optional parameter such as an alias name, passing null is the same as omitting it.

You can also specify sub-queries in joins:

            alert(
                squel.select()
                    .from('marks', 'm')
                    .join( squel.select().from('students'), 's', 's.id = m.id' )
            );
            /*  SELECT * FROM marks `m` INNER JOIN (SELECT * FROM students) `s` ON (s.id = m.id) */
        

Filtering

You can add WHERE clause filtering to your query very easily:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .where("name = 'Thomas'")
            );
            /*  SELECT id FROM students WHERE (name = 'Thomas')  */
        

Parameters substitution is supported:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .where("score = ?", squel.select().field('MAX(score)').from('scores'))
            );
            /*  SELECT id FROM students WHERE (score = (SELECT MAX(score) FROM scores))  */
        
For more information on using parameterized queries see the parameters documentation section.

Multiple filters are automatically combined using AND:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .where("name = 'Thomas'")
                    .where("age > 18")
            );
            /*  SELECT id FROM students WHERE (name = 'Thomas') AND (age > 18) */
        

Also filter using OR or any other operator you like:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .where("name = 'Thomas' OR age > 18")
                    .where("id BETWEEN 200 and 300")
            );
            /*  SELECT id FROM students WHERE (name = 'Thomas' OR age > 18) AND (id BETWEEN 200 and 300) */
        

You can also pass in Expressions:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .where(
                        squel.expr().and("name = 'Thomas'").or("age > 18")
                    )
            );
            /*  SELECT id FROM students WHERE (name = 'Thomas' OR age > 18) */
        

Sorting

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .order("id")
                    .order("name")
            );
            /*  SELECT id FROM students ORDER BY id ASC, name ASC */
        

Use the second argument of order() to change the direction of a sort:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .order("id")
                    .order("name", false)  /* using TRUE instead would be the same as omitting it. */
            );
            /*  SELECT id FROM students ORDER BY id ASC, name DESC */
        

Additional arguments count as parameter values, e.g. for custom sort functions::

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .order("DIST(?, ?)", true, 1, 2)
            );
            /*  SELECT id FROM students ORDER BY DIST(1, 2) ASC */
        

Grouping

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .group("id")
            );
            /*  SELECT id FROM students GR0UP BY id */
        

Grouping on multiple fields is supported:

            alert(
                squel.select()
                    .field("id")
                    .from("students")
                    .group("id")
                    .group("students.name")
            );
            /*  SELECT id FROM students GR0UP BY id, students.name */
        

Ranges

To LIMIT the number of results:

            alert(
                squel.select()
                    .from("students")
                    .limit(10)
            );
            /*  SELECT * FROM students LIMIT 10 */
        

To remove the previously set limit:

            alert(
                squel.select()
                    .from("students")
                    .limit(10)
                    .limit(0)
            );
            /*  SELECT * FROM students */
        

To specify the OFFSET of the first row to return:

            alert(
                squel.select()
                    .from("students")
                    .offset(102)
            );
            /*  SELECT * FROM students OFFSET 102 */
        

Same as for limit(), you can remove a previously set offset:

            alert(
                squel.select()
                    .from("students")
                    .offset(1)
                    .offset(0)
            );
            /*  SELECT * FROM students */
        

Unions

A simple UNION query:
            alert(
                squel.select()
                    .from("students")
                    .union( 
                        squel.select()
                            .from('scores') 
                    )
                    .union( 
                        squel.select()
                            .from('batches') 
                    )
            );
            /*  SELECT * FROM students UNION (SELECT * FROM scores) UNION (SELECT * FROM batches) */
        

UPDATE

To get an instance of the UPDATE query builder:

            var q = squel.update();
        

You need to supply at least one table name and one field to update:

            alert(
                squel.update()
                    .table("students")
                    .set("name", "Thomas")
            );
            /*  UPDATE students SET name = "Thomas" */
        

Multiple table names can be supplied along with aliases:

            alert(
                squel.update()
                    .table("students")
                    .table("teachers", "t")
                    .set("t.name", "Fred")
            );
            /*  UPDATE students, teachers `t` SET t.name = "Fred" */
        

Field values

Not all field values within a query need to be surrounded by quotes. Squel figures out how to represent each field value based on its runtime type:

            alert(
                squel.update()
                    .table("students")
                    .set("name", "Fred")
                    .set("age", 29)
                    .set("score", 1.2)
                    .set("graduate", false)
                    .set("level", squel.select().field('MAX(level)').from('levels'))
            );
            /*  UPDATE students SET name = "Fred", age = 29, score = 1.2, graduate = FALSE, level = (SELECT MAX(level) FROM levels) */
        

You can turn off automatic quoting on a per-field basis:

            alert(
                squel.update()
                    .table("students")
                    .set("time", "GETDATE()", {
                        dontQuote: true
                    })
                    .set("city", "London")
            );
            /*  UPDATE students SET time = GETDATE(), city = "London" */
        

You can even use NULL values:

            alert(
                squel.update()
                    .table("students")
                    .set("name", "Fred")
                    .set("age", 29)
                    .set("nickname", null)
            );
            /*  UPDATE students SET name = "Fred", age = 29, nickname = NULL */
        

Hint: Squel can also be configured to handle Object instances by registering custom value types.

If the second parameter to set() is not provided then the field name is assumed to be an operation:

            alert(
                squel.update()
                    .table("students")
                    .set("age = age + 1")
            );
            /*  UPDATE students SET age = age + 1 */
        

You can also set multiple fields in a single call:

            alert(
                squel.update()
                    .table("students")
                    .setFields({ age: 23, name: 'Fred' })
            );
            /*  UPDATE students SET age = 23, name = 'Fred' */
        

Parameter substitution for parameterized queries is also supported, see the section on Parameters.

Filtering, sorting and limits

The where(), order() and limit() methods are supported the same way they are by the SELECT builder:

            alert(
                squel.update()
                    .table("students")
                    .set("name", "Fred")
                    .set("age", 29)
                    .where("id > 5")
                    .where("id < 102")
                    .order("id", false)
                    .limit(5)
            );
            /*  UPDATE students SET name = "Fred", age = 29 WHERE (id > 5) AND (id < 102) ORDER BY id DESC LIMIT 5 */
        

DELETE

To get an instance of the DELETE query builder:

            var q = squel.delete();
        

You can also use the alias remove():

            var q = squel.remove();
        

You need to supply at least the table name:

            alert(
                squel.delete()
                    .from("students")
            );
            /*  DELETE FROM students */
        

Joins

The join() and related methods are supported the same way they are by the SELECT builder:

            alert(
                squel.delete()
                    .from("students", "s")
                    .outer_join("marks", "m", "m.student_id = s.id")
            );
            /*  DELETE FROM students `s` OUTER JOIN marks `m` ON (m.student_id = s.id) */
        

Filtering, sorting and limits

The where(), order() and limit() methods are supported the same way they are by the SELECT builder:

            alert(
                squel.delete()
                    .from("students")
                    .where("id > 5")
                    .where("id < 102")
                    .order("id", false)
                    .limit(5)
            );
            /*  DELETE FROM students WHERE (id > 5) AND (id < 102) ORDER BY id DESC LIMIT 5 */
        

INSERT

To get an instance of the INSERT query builder:

            var q = squel.insert();
        

At least the table name and one field must be supplied:

            alert(
                squel.insert()
                    .into("students")
                    .set("name", "Thomas")
            );
            /*  INSERT INTO students (name) VALUES ("Thomas") */
        

Squel out how to treat each field value based on its runtime type:

            alert(
                squel.insert()
                    .into("students")
                    .set("name", "Thomas")
                    .set("age", 29)
                    .set("score", 90.2)
                    .set("graduate", true)
                    .set("nickname", null)
                    .set("level", squel.select().field('MAX(level)').from('levels'))
            );
            /*  INSERT INTO students (name, age, score, graduate, nickname, level) 
                VALUES ('Thomas', 29, 90.2, TRUE, NULL, (SELECT MAX(level) FROM levels)) */
        

You can turn off automatic quoting on a per-field basis:

            alert(
                squel.insert()
                    .into("students")
                    .set("time", "GETDATE()", {
                        dontQuote: true
                    })
                    .set("city", "London")
            );
            /*  INSERT INTO students (time, city) VALUES(GETDATE(), "London") */
        

Multiple fields and rows

You can set multiple fields in a single call:

            alert(
                squel.insert()
                    .into("students")
                    .setFields({ name: "Thomas", age: 29 })
            );
            /*  INSERT INTO students (name, age) VALUES ('Thomas', 29) */
        

You can even do a multi-row insert:

            alert(
                squel.insert()
                    .into("students")
                    .setFieldsRows([
                      { name: "Thomas", age: 29 },
                      { name: "Jane", age: 31 }
                    ])
            );
            /*  INSERT INTO students (name, age) VALUES ('Thomas', 29), ('Jane', 31) */
        
Note: When doing a multi-row insertion every row specified in the parameter to setFieldsRows should have the same field names specified. Squel will throw an error if this is not the case.

Parameters

Note: Squel previously provided the usingValuePlaceholders option as a way of enabling parameterized queries. This has been deprecated as of version 2.0.0 and should NOT be used.

Squel makes it very easy to build and use parameterized queries. Every query builder provides a toParam() method which gives you final query string separate to any parameters values previously passed in:

        alert(JSON.stringify(
          squel.select()
            .from("students")
            .where("a = ? AND b = ?", "test", true)
            .order("CALC(?, ?)", true, 1.2, false)
            .toParam()
        ));

        /*
          {
            text:  SELECT * FROM students WHERE (a = ? AND b = ?) ORDER BY CALC(?, ?) ASC,
            values:  [ 'test', true, 1.2, false ]
          }
        */
      

Using sub-queries as parameter values:

            alert(JSON.stringify(
              squel.select()
                .from("students")
                .where("a = ? AND b IN ?", "test", squel.select().field('score').from('results').where('c = ?', 5))
                .toParam()
            ));

            /*
              {
                text:  SELECT * FROM students WHERE (a = ? AND b IN (SELECT score FROM results WHERE c = ?)),
                values:  [ 'test', 5 ]
              }
            */
        

A more complex example involving sub-queries and unions:

            alert(JSON.stringify(
              squel.select()
                .from("students")
                .where("a IN ?", squel.select().field('score').from('results').where('c = ?', 5))
                .union(
                    squel.select().field('age').from('states').where('person = ?', 
                        squel.select().field('id').from('students').where('name = ?', 'John').limit(1)
                    )
                )
                .toParam()
            ));

            /*
              {
                text:  SELECT * FROM students WHERE (a IN (SELECT score FROM results WHERE (c = ?))) UNION (SELECT age FROM states WHERE (person = (SELECT id FROM students WHERE (name = ?) LIMIT 1))),
                values:  [ 5, 'John' ]
              }
            */
        

As you can see the parameter values are not specially formatted as they normally are when toString() is called. Also note that the parameter placeholders are non-numbered by default. To enable numbering use the numberedParameters option:

        alert(JSON.stringify(
          squel.insert({ numberedParameters: true })
            .into("students")
            .set("a", "test")
            .set("b", 1)
            .set("c", null)
            .toParam()
        ));

        /*
          {
            text:  INSERT INTO students (a, b, c) VALUES ($1, $2, $3)
            values:  [ 'test', 1, null ]
          }
        */
      
Note: For the Postgres flavour numbered parameters are enabled by default.

You can both turn on numbered parameters and change the start number in one go:

        alert(JSON.stringify(
          squel.insert()
            .into("students")
            .set("a", "test")
            .set("b", 1)
            .set("c", null)
            .toParam({ numberedParametersStartAt: 3 })
        ));

        /*
          {
            text:  INSERT INTO students (a, b, c) VALUES ($3, $4, $5)
            values:  [ 'test', 1, null ]
          }
        */
      

The values array returned is always flat, even for multi-row inserts:

            alert(JSON.stringify(
                squel.insert()
                    .into("students")
                    .setFieldsRows([
                      { name: "Thomas", age: 29 },
                      { name: "Jane", age: 31 }
                    ])
                    .toParam()
            ));
            /*
              {
                text:  INSERT INTO students (name, age) VALUES (?, ?), (?, ?)
                values:  [ 'Thomas', 29, 'Jane', 31 ]
              }
            */
        

Array values can be used to create IN clauses:

          alert(JSON.stringify(
              squel.select()
                  .field("id")
                  .from("students")
                  .where("age IN ?", [18, 19, 20])
                  .toParam()
          ));

          /*
            {
              text:  SELECT id FROM students WHERE (age IN (?, ?, ?)),
              values: [ 18, 19, 20 ]
            }
          */
      

In general it is better to use toParam() rather than toString() when constructing the final query as it gives you the opportunity to use your database engine methods to safely escape and interpolate your parameters.

Automatic quotes

By default Squel does not add quotes around table names and field names. But you can tell it to do so using the autoQuoteTableNames and autoQuoteFieldNames options:

        alert(
          squel.select({ autoQuoteTableNames: true, autoQuoteFieldNames: true })
            .from("students", "s")
            .field("s.name", "Student name")
        );

        /*   SELECT `s`.`name` AS "Student name" FROM `students` `s`  */
      

Notice how squel was smart enough to detect the period separator within s.name when quoting. You can turn off this behaviour if you wish:

        alert(
          squel.select({ autoQuoteTableNames: true, autoQuoteFieldNames: true })
            .from("students", "s")
            .field("s.name", "Student name", { ignorePeriodsForFieldNameQuotes: true })
        );

        /*   SELECT `s.name` AS "Student name" FROM `students` `s`  */
      

You can also customize the quote character using the nameQuoteCharacter option:

        alert(
          squel.select({ autoQuoteTableNames: true, autoQuoteFieldNames: true, nameQuoteCharacter: '|' })
            .from("students")
            .field("name", "Student name")
        );

        /*   SELECT |name| AS "Student name" FROM |students|  */
      

As you can see above, Squel does however automatically add quotes to alias names. These too can be customized:

        alert(
          squel.select({ tableAliasQuoteCharacter: '|', fieldAliasQuoteCharacter: '~' })
            .from("students", "s")
            .field("name", "Student name")
        );

        /*   SELECT name AS ~Student name~ FROM students |s|  */
      

And you can turn off automatic alias quoting if you so desire:

        alert(
          squel.select({ autoQuoteAliasNames: false })
            .from("students", "s")
            .field("name", "Student_name")
        );

        /*   SELECT name AS Student_name FROM students s  */
      

Expressions

Squel lets you use use complex expressions strings in WHERE and ON clauses. For example:

            alert(
                squel.select()
                    .from("students")
                    .where("(id < 500 AND (id > 100 OR name <> 'Thomas') AND "
                            + "(age BETWEEN 20 AND 25 OR (name <> 'Fred'))) OR (nickname = 'Hardy')")
            );
            /*  SELECT * FROM students WHERE
                    ((id < 500 AND (id > 100 OR name <> 'Thomas') AND (age BETWEEN 20 AND 25 OR (name <> 'Fred')))
                        OR (nickname = 'Hardy')) */
        

But having to change an expression string like that later on will be error-prone. It would be nice if you could build it the same way you build queries. Luckily Squel provides an expression builder just for this purpose. To get an instance of the builder:

            var q = squel.expr();
        

To build the above expression string these are the calls you would make:

            alert(
                squel.expr()
                    .and("id < 500")
                    .and_begin()
                        .or("id > 100")
                        .or("name <> 'Thomas'")
                    .end()
                    .and_begin()
                        .or("age BETWEEN 20 AND 25")
                        .or("name <> 'Fred'")
                    .end()
                    .or("nickname = 'Hardy'")
            );
            /*  id < 500 AND (id > 100 OR name <> 'Thomas') AND (age BETWEEN 20 AND 25 OR name <> 'Fred')
                    OR nickname = 'Hardy'
            */
        

Straight away the benefit of using the expression builder can be seen as it has simplified the expression (AND has precendence over OR). Not to mention that it's easier to figure out the meaning of the expression looking at this code than from the big string we were using earlier.

As a convenience expression builder instances can be used in calls to where() and join() when using the query builders:

            alert(
                squel.select()
                    .field("s.id")
                    .from("students", "s")
                    .where(
                        squel.expr()
                            .and("s.name <> 'Fred'")
                            .or_begin()
                                .or("s.id = 5")
                                .or("s.id = 6")
                            .end()
                    )
                    .join("teachers", "t",
                        squel.expr()
                            .and("s.id = t.sid")
                            .and("t.name = 'Frances'")
                    )
            );
            /*
                SELECT s.id FROM students `s`
                    INNER JOIN teachers `t` ON (s.id = t.sid AND t.name = 'Frances')
                        WHERE (s.name <> 'Fred' AND (s.id = 5 OR s.id = 6))
            */
        

Expressions can be parameterized too:

            alert(JSON.stringify(
                squel.expr()
                    .and("s.name <> ?", 'Fred')
                    .or_begin()
                        .or("s.id = ?", 5)
                        .or("s.id = ?", 6)
                    .end()
                    .toParam()
            ));
            /*
                { 
                    "text": "s.name <> ? AND (s.id = ? OR s.id = ?))", 
                    "values": ['Fred', 5, 6] 
                }
            */
        

Custom value types

Sometimes you might want to override how Squel formats certainst types of values, e.g. Date instances. You could do the following:

            var myDate = new Date(2012, 4, 22),
                myDate2 = new Date(2013, 5, 30);

            alert(
                squel.update()
                    .table("students")
                    .set("start_date", myDate.getFullYear() + '-' + myDate.getMonth() + '-' + myDate.getDate())
                    .set("end_date", myDate2.getFullYear() + '-' + myDate2.getMonth() + '-' + myDate2.getDate())
            );
            /*  UPDATE students SET start_date = '2012-4-22', end_date = '2013-5-30' */
      

Functional but no so elegant. A better approach is to register the Date object type with Squel as a custom value type. We will need to supply a handler function which will get called whenever an object of type Date is encountered:

            var myDate = new Date(2012, 4, 22),
                myDate2 = new Date(2013, 5, 30);

            /* Tell Squel how to handle Date objects */
            squel.registerValueHandler(Date, function(date) {
              return date.getFullYear() + '-' + date.getMonth() + '-' + date.getDate();
            });

            alert(
                squel.update()
                    .table("students")
                    .set("start_date", myDate)
                    .set("end_date", myDate2)
            );
            /*  UPDATE students SET start_date = '2012-4-22', end_date = '2013-5-30' */
      

We can register any type of object as a custom value type, not just Date. Squel checks to see if the runtime type of a passed-in value matches one of the registered value types - meaning that sub-types are automatically supported.

            /* OOP Inheritance mechanism (substitute your own favourite library for this!) */
            Function.prototype.inheritsFrom = function( parentClassOrObject ) {
              this.prototype = new parentClassOrObject;
              this.prototype.constructor = this;
              this.prototype.parent = parentClassOrObject.prototype;
            };

            /* Base type */
            var ClassA = function() { this.a = 1; };

            /* Sub-type */
            var ClassB = function() { this.a = 2; };
            ClassB.inheritsFrom(ClassA);

            /* Register base type */
            squel.registerValueHandler(ClassA, function(obj) {
              return obj.a;
            });

            alert(
                squel.update()
                    .table("students")
                    .set("value", new ClassB())
            );
            /*  UPDATE students SET value = 2 */
      

We can even register handlers for primitive types such as strings and booleans. Simply pass in the primitive type name as a string:

            squel.registerValueHandler('boolean', function(v) {
              return v ? 'YES': 'NO';
            });

            alert(
                squel.update()
                    .table("students")
                    .set("value", true)
            );
            /*  UPDATE students SET value = 'YES' */
      

We can even override the registered handler for a value type on a per-instance basis.

            /* Global handler */
            squel.registerValueHandler(Date, function(date) {
              return date.getFullYear();
            });

            alert(
              squel.update()
                .registerValueHandler(Date, function(date) {
                  return '[' + date.getFullYear() + ']';
                })
                .table('students')
                .set('value', new Date(2013,5,1))
            );
            /*  UPDATE students SET value = '[2013]' */
      

Custom value types are processed correctly for parameterised queries:

            var myDate = new Date(2012, 4, 22),
                myDate2 = new Date(2013, 5, 30);

            /* Tell Squel how to handle Date objects */
            squel.registerValueHandler(Date, function(date) {
              return date.getFullYear() + '-' + date.getMonth() + '-' + date.getDate();
            });

            alert(JSON.stringify(
                squel.select()
                    .from("students")
                    .where("start_date >= ?", myDate)
                    .where("end_date <= ?", myDate2)
                    .toParam()
            ));

            /*  
            {
              text:  SELECT * FROM students WHERE (start_date >= ?) AND (end_date <= ?),
              values: [ '2012-4-22', '2013-5-30' ]
            }
            */                
      

Custom queries

You can customize Squel's query building mechanism quite easily. For instance, if you wanted to add OFFSET clauses to UPDATE queries you could do it as such:

        /* We create a convenience method to make it easy to instantiate our customized UPDATE builder */
        squel.myupdate = function(options) {
          return squel.update(options, [
            new squel.cls.StringBlock(options, 'UPDATE'),
            new squel.cls.UpdateTableBlock(options),
            new squel.cls.SetFieldBlock(options),
            new squel.cls.WhereBlock(options),
            new squel.cls.OrderByBlock(options),
            new squel.cls.OffsetBlock(options),
            new squel.cls.LimitBlock(options)
          ]);
        };

        alert(
          squel.myupdate()
            .table('students')
            .set('status', 'active')
            .limit(10)
            .offset(2)
        );

        /* UPDATE students SET status = 'active' OFFSET 2 LIMIT 10 */
      

Hopefully you can see that it is possible to totally override the built-in query building logic. Also notice that each building block within a query can have a different set of options applied to it. Check out squel.coffee to see the available building blocks.

You can also build other types of queries and query clauses not already included in Squel. Let's say you wanted to build a query structured as follows: PRAGMA {command} {param}:

        /* OOP Inheritance mechanism (substitute your own favourite library for this!) */
        Function.prototype.inheritsFrom = function( parentClassOrObject ) {
          this.prototype = new parentClassOrObject;
          this.prototype.constructor = this;
          this.prototype.parent = parentClassOrObject.prototype;
        };


        /* Create the 'command' clause */

        var CommandBlock = function() {};
        CommandBlock.inheritsFrom(squel.cls.Block);

        /* methods prefixed with '_' are private and will not get exposed within the query builder */
        CommandBlock.prototype._command = function(command) {
          this.command = command;
        };

        /* this method will get exposed within the query builder */
        CommandBlock.prototype.flush = function() {
          this._command('flush');
        };

        /* output the query clause */
        CommandBlock.prototype.buildStr = function() {
          return this.command.toUpperCase();
        };


        /* Create the 'param' clause */

        var ParamBlock = function() {};
        ParamBlock.inheritsFrom(squel.cls.Block);

        ParamBlock.prototype.param = function(p) {
          this._p = p;
        };

        ParamBlock.prototype.buildStr = function() {
          return this._p;
        };


        /* Create the 'PRAGMA' query builder */

        var PragmaQuery = function(options) {
          this.parent.constructor.call(this, options, [
              new squel.cls.StringBlock(options, 'PRAGMA'),
              new CommandBlock(),
              new ParamBlock()
          ]);
        };
        PragmaQuery.inheritsFrom(squel.cls.QueryBuilder);


        /* Create squel.pragma() convenience method */

        squel.pragma = function(options) {
          return new PragmaQuery(options)
        };


        /* Try it out! */

        alert(
          squel.pragma()
            .flush()
            .param('students')
        );

        /* 'PRAGMA FLUSH students' */
      

Cloning

You can create a copy of a query builder instance using its clone() method. For example:

          var select1 = squel.select().from('students');

          var select2 = select1.clone().field('id').where('name = "david"');

          alert( select1 );

          /* SELECT * FROM students */

          alert( select2 );

          /* SELECT id FROM students WHERE (name = "david") */
      

Here is an example using an INSERT builder:

          var ins = squel.insert().into('students').set('name', 'David');

          var insMathew = ins.clone().set('name', 'Mathew');

          var insMark = insMathew.clone().set('name', 'Mark');

          alert( insMathew );

          /* INSERT INTO students (name) VALUES('Mathew') */

          alert( insMark );

          /* INSERT INTO students (name) VALUES('Mark') */
      

Database engines

Although you can use Squel's query customization mechanism to add support for your desired commands it would be nice if Squel supported non-standard SQL commands for common database engines out of the box.

Well it actually does. Squel supports of the concept of SQL flavours, whereby a flavour is a non-standard version of SQL which can be loaded and used at runtime. At the moment Squel provides support for the Postgres, MSSQL/Transact-SQL and MySQL flavours of SQL.

Note: The API docs have more details on the specific features supported by each flavour.

Postgres

The postgres flavor uses numbered query parameters by default. It also provides the RETURNING clause:
        squel.useFlavour('postgres');

        alert(JSON.stringify(
          squel.insert()
            .into('table')
            .set('field', 5)
            .returning('*')
            .toParam()
        ));

        /*  
            {
                text: 'INSERT INTO table (field) VALUES ($1) RETURNING *'
                values: [5]
            }
        */
      

MySQL

The mysql flavour provides the ON DUPLICATE KEY UPDATE clause:
        squel.useFlavour('mysql');

        alert(JSON.stringify(
          squel.insert()
            .into('table')
            .setFields({
                field1: 'abc',
                field2: 3
            })
            .onDupUpdate('field1', 'upd')
            .toParam()
        ));

        /*  
            {
                text: 'INSERT INTO table (field1, field2) VALUES (?, ?) ON DUPLICATE KEY UPDATE field1 = ?'
                values: ['abc', 3, 'upd']
            }
        */
      

MSSQL/Transact-SQL

Default date formatting:

        squel.useFlavour('mssql');

        alert(
          squel.insert()
            .into('table')
            .setFields({
                field1: new Date('2012-12-12T04:30:00Z')
            })
            .toString()
        );

        /*  
            INSERT INTO table (field1) VALUES('2012-12-12 4:30:0')
        */
      

TOP:

        squel.useFlavour('mssql');

        alert(
          squel.select()
            .from('table')
            .field('field')
            .top(10)
            .toString()
        );

        /*  
            SELECT TOP (10) field FROM table
        */
      

OFFSET and FETCH NEXT:

        squel.useFlavour('mssql');

        alert(
          squel.select()
            .from('table')
            .field('field')
            .limit(10)
            .offset(5)
            .toString()
        );

        /*  
            SELECT field FROM table OFFSET 5 ROWS FETCH NEXT 10 ROWS ONLY
        */
      

OUTPUT INSERTED:

        squel.useFlavour('mssql');

        alert(
          squel.update()
            .table('table')
            .output('id', 'blah')
            .set('field', 1)
            .toString()
        );

        /*  
            UPDATE table SET field = 1 OUTPUT INSERTED.id AS blah
        */
      
        squel.useFlavour('mssql');

        alert(
          squel.insert()
            .into('table')
            .output('id')
            .set('field', 1)
            .toString()
        );

        /*  
            INSERT INTO table (field) OUTPUT INSERTED.id VALUES (1)
        */