SQLQueryString

struct SQLQueryString

Overview

Query strings are primarily intended for use with SQLRawBuilder, providing for the inclusion of bound parameters in otherwise “raw” queries. The API also supports some of the more commonly used quoting functionality. Query strings are also SQLExpressions, allowing them to be used almost anywhere in SQLKit.

A corollary to this is that, while a given SQLQueryString can represent an entire complete “query” to execute against a database, it can also - as with any SQLExpression but particularly similarly to SQLStatement - represent any lesser fragment of SQL right down to an empty string, or anywhere in between.

Example usage:

// As an entire query:
try await database.raw("""
    UPDATE \(ident: "foo")
        SET \(ident: "bar")=\(bind: value)
        WHERE \(ident: "baz")=\(literal: "bop")
    """).run()

// As an SQL fragment (albeit in an extremely contrived fashion):
try await database.update("foo")
    .set("bar", to: value)
    .where("\(ident: "baz")" as SQLQueryString, .equal, "\(literal: "bop")" as SQLQueryString)
    .run()

SQLQueryString’s additional interpolations (such as \(ident:), \(literal:), etc., as well as the ability to embed arbitrary expressions with \(_:)) are useful in particular for writing raw queries which are nonetheless compatible with multiple SQL dialects, such as in the following example:

let messyIdentifer = someCondition ? "abcd{}efgh" : "marmalade!!" // invalid identifiers if not escaped
try await database.raw("""
    SELECT \(ident: messyIdentifier) FROM \(ident: "whatever") WHERE \(ident: "x")=\(bind: "foo")
    """).all()
// This query renders differently in various dialect:
// - PostgreSQL: SELECT "abcd{}efgh" FROM "whatever" WHERE "x"=$0 ["foo"]
// -      MySQL: SELECT `abcd{}efgh` FROM `whatever` WHERE `x`=?  ["foo"]
// -     SQLite: SELECT "abcd{}efgh" FROM "whatever" WHERE "x"=?0 ["foo"]