Classes

Subclasses of the AuxiliaryTable class are describing a Table that is used in WITH clauses.

Usage Example:

In this example, an AuxiliaryTable class is defined containing two columns. A ToDoTable (as defined in Table), a PersonTable (as defined in Column) and a connection instance are initialized. An instance of the AuxiliaryTable is then initialised from Column instances in “todotable”. This AuxiliaryTable is then used to create an SQL WITH query. A description of the created query is then printed.

class AuxTable: AuxiliaryTable {
   let tableName = "aux_table"
   let name = Column("name")
   let finished = Column("finished")
}

let todotable = ToDoTable()          // ToDoTable() is a previously defined `Table` class
let persontable = PersonTable()      // PersonTable() is a previously defined `Table` class
let connection = PostgreSQLConnection(host: "localhost", port: 5432, options: [.databaseName("ToDoDatabase")])

let withTable = AuxTable(as: Select(todotable.toDo_completed.as("finished"), todotable.toDo_title.as("name"), from: todotable))
let withQuery = with(withTable, Select(withTable.finished, persontable.monthlyPay, from: persontable).join(withTable).on(persontable.name == withTable.name))
let stringQuery = try connection.descriptionOf(query: withQuery)
print(stringQuery)
// Prints WITH aux_table AS (SELECT toDoTable.toDo_completed AS finished, toDoTable.toDo_title AS name FROM toDoTable) SELECT aux_table.finished, personTable.monthlyPay FROM personTable JOIN aux_table ON personTable.firstName = aux_table.name

The Column class is used to represent a single column in an SQL table in Swift. A combination of columns are used to construct a Table class which matches a specific table in an SQL database. The Column class details the column name, the table the column belongs to, any SQL keywords which apply to the column and the data type of the column.

Usage Example:

In this example, a person Table class, containing three instances of the Column class, is defined.

 public class PersonTable : Table {
     let tableName = "personTable"
     let person_id = Column("person_id", Int32.self, autoIncrement: true, primaryKey: true, notNull: true, unique: true)
     let name = Column("name", String.self, notNull: true)
     let monthlyPay = Column("monthlyPay", Int32.self)
 }

This class implements a first in, first out connection pool. The pool maintains a cache of ConnectionPoolConnection instances, which can be reused for future requests, to enhance performance.

Usage Example:

In most cases, you will create a connection pool using a plugin, such as SwiftKuery-postgreSQL, which implements this class. You would then call the specific plugin with the required options. If you wish to create the a ConnectionPool manually you can use this example. Two closures to generate and release Connection instances are defined. A connection pool is then initialized with the defined closures and options. A single Connection is then retrieved from the pool.

 let options = ConnectionPoolOptions(initialCapacity: 2, maxCapacity: 5, timeout: 1000)
 let connectionGenerator: () -> Connection? = {
    let connection = PostgreSQLConnection(host: "localhost", port: 5432, options: [.databaseName("ExampleDatabase")])
    return connection
 }
 let connectionReleaser: (_ connection: Connection) -> () = { connection in
    connection.closeConnection()
 }
 let connectionPool = ConnectionPool(options: options, connectionGenerator: connectionGenerator, connectionReleaser: connectionReleaser)
 guard let singleConnection = connectionPool.getConnection() else {
    // handle error
    return
 }

Note: This class is usually initialised by the ConnectionPool instance. Therefore, a standard user will not use this class unless they are creating their own SQL plugin.

This class uses a Connection instance and a ConnectionPool instance to implement a wrapper for the Connection class. It implements the functions of the Connection protocol, in addition to the closeConnection() function for releasing a Connection instance from the ConnectionPool.

Usage Example:

In this example, a ConnectionPool instance is initialized (parameters defined in docs for ConnectionPool). A ConnectionPoolConnection instance is created by calling connectionPool.getConnection(). This connection is then released from the pool.

let connectionPool = ConnectionPool(options: options, connectionGenerator: connectionGenerator, connectionReleaser: connectionReleaser)
let connection = connectionPool.getConnection()
connection.closeConnection()

Undocumented

A class to help with migration between two versions of a table.

Usage Example:

The suggested usage is to keep versions of the table classes somewhere in the application code:

public class MyTable_v0: Table {
    let a = Column("a", ...)
    let b = Column("b", ...)
    let tableName = "MyTable"
}
public class MyTable_v1: Table {
    let b = Column("b", ...)
    let c = Column("c", ...)
    let tableName = "MyTable"
}

And use a typealias to refer to the current version of the table class in the application:

typealias MyTable = MyTable_v0
let t = MyTable()
let q = Select(from: t)
...

The migration code from v0 to v1 should be something like this:

let t0 = MyTable_v0()
let t1 = MyTable_v1()
let migration0 = Migration(from: t0, to: t1, using: connection)
migration0.alterTableAdd(column: t1.c) { result in ... }

And raw alternations, if needed:

let dropColumnQuery = "ALTER TABLE " + t1.tableName + " DROP COLUMN " + t0.a.name
connection.execute(dropColumnQuery) { result in ... }

Note: Changing the QueryBuilder should only be needed for adding support for a new database plugin.

QueryBuilder is used in code dealing with variances between the various database engines. As different databases have different query syntax, sometimes changes need to be made when generating the actual SQL statement to run. Additional changes should be made by updating the QueryBuilder substitutions array. Every query component then builds its string representation using that array.

Usage Example:

In this example, a QueryBuilder for PostgreSQL is initialized. Parameters are set for PostgreSQL and string keywords for SQL queries are substituted into the queryBuilder. The queryBuilder is then used to create a string description of the Table class instance called todotable.

let queryBuilder = QueryBuilder(withDeleteRequiresUsing: true, withUpdateRequiresFrom: true, createAutoIncrement: createAutoIncrement)
queryBuilder.updateSubstitutions([QueryBuilder.QuerySubstitutionNames.ucase : "UPPER",
   QueryBuilder.QuerySubstitutionNames.lcase : "LOWER",
   QueryBuilder.QuerySubstitutionNames.len : "LENGTH",
   QueryBuilder.QuerySubstitutionNames.numberedParameter : "$",
   QueryBuilder.QuerySubstitutionNames.namedParameter : "",
   QueryBuilder.QuerySubstitutionNames.double : "double precision"
])
let description = try todotable.build(queryBuilder: queryBuilder)

Represents a query result set. The rows are accessable either in a blocking fashion using a RowSequence or in a non-blocking fashion using nextRow() function.

The Table class is used to create a class in Swift that maps to an external SQL database table. To reference a table, you must implement this class and define the table name as well as the Column instances present. The Table class then provides methods to build SQL String descriptions for the various database engines.

Usage Example:

In this example, we define a ToDoTable class which maps to an existing table in a SQL database. An instance of the ToDoTable class is then initialized and used in a SQL SELECT query to retrieve the data from the table within the external database.

public class ToDoTable: Table {
   let tableName = "toDoTable"
   let toDo_id = Column("toDo_id", Int32.self, autoIncrement: true, primaryKey: true, notNull: true, unique: true)
   let toDo_title = Column("toDo_title", String.self, notNull: true)
   let toDo_completed = Column("toDo_completed", Bool.self, defaultValue: false)
}

public class Application {
   let selectQuery = Select(from: ToDoTable())
}