Kitura

Docs Build Status - Master macOS Linux Apache 2 Slack Status

Swift-Kuery

SQL database abstraction layer

Summary

Swift-Kuery is a pluggable SQL database driver/SDK abstraction layer. Its main idea is to unify the APIs to the various relational databases, providing a Swifty yet SQL-like API. This allows easy switching between databases and forms the basis for an Object-Relational Mapping (ORM) framework.

Swift-Kuery-ORM is an ORM, built on top of Swift-Kuery, which allows you to simplify the persistence of model objects with your server.

Swift-Kuery is an easy to learn, consumable framework that comes with a set of implemented plugins.

Table of Contents

Examples

This example demonstrates how to execute an SQL query using Swift-Kuery with the Swift-Kuery-PostgreSQL plugin.

The starting point for this example is an existing Swift package. If you don’t have one already, create and enter a directory named e.g. SwiftKueryExample. Now run the swift package’s init command, to create an executable type, by running swift package init --type executable.

Creating A PostgreSQL Database

  1. Install PostgreSQL

    Mac

    brew install postgresql

    Ubuntu Linux

    sudo apt-get install postgresql postgresql-contrib

  2. Create a school database

    createdb school
    psql school
    
  3. Create a grades table

    CREATE TABLE grades (
        id varchar(100) PRIMARY KEY,
        course text NOT NULL,
        grade integer
    );  
    

Update your Package.swift file

Add Swift-Kuery-PostgreSQL to your Package.swift. This will bring in Swift-Kuery as well.

dependencies: [
    ...
    // Add this line
    .package(url: "https://github.com/IBM-Swift/Swift-Kuery-PostgreSQL.git", from: "1.0.0"),
  ],
  targets: [
    .target(
      name: ...
      // Add the module to your target(s)
      dependencies: [..., "SwiftKueryPostgreSQL"]),
  ]

Executing SQL queries

Inside the main.swift file:

  1. Add SwiftKuery and SwiftKueryPostgreSQL to your import statements:

    import SwiftKuery
    import SwiftKueryPostgreSQL
    
  2. Create a Table class, which matches the grades table you created in the database:

    class Grades: Table {
    let tableName = "Grades"
    let id = Column("id", Int32.self, primaryKey: true)
    let course = Column("course", String.self)
    let grade = Column("grade", Int32.self)
    }
    let grades = Grades()
    
  3. Create a pool of connections to PostgreSQL:

    let pool = PostgreSQLConnection.createPool(host: "localhost", port: 5432, options: [.databaseName("school")], poolOptions: ConnectionPoolOptions(initialCapacity: 10, maxCapacity: 50, timeout: 10000))
    
  4. Create some example students:

    let students: [[Any]] = [[0, "computing", 92], [1, "physics", 75], [2, "history", 83]]
    
  5. Connect to database and perform an SQL query:

    if let connection = pool.getConnection() {
    let insertQuery = Insert(into: grades, rows: students)
    connection.execute(query: insertQuery) { insertResult in
        connection.execute(query: Select(from: grades)) { selectResult in
            if let resultSet = selectResult.asResultSet {
                for row in resultSet.rows {
                    print("Student \(row[0] ?? ""), studying \(row[1] ?? ""), scored \(row[2] ?? "")")
                }
            }
        }
    }
    }
    
  6. Save the main.swift file. Run swift build to build the executable.

  7. Run the executable .build/debug/<yourPackageName>.

This will print the id, course and grade for each student, which are queried from the database:

Student 0, studying computing, scored 92
Student 1, studying physics, scored 75
Student 2, studying history, scored 83

If you go to your database with psql school and enter TABLE grades; you can see that the table has been populated with the student data.

SQL Injection Prevention using Parameterization

Unsanitized data that is used in dynamic queries is one of the most common causes of SQL injection vulnerabilities. Parameterizing queries can help to prevent SQL injection attacks.

The following code is vulnerable to SQL injection if supplied_key1 or supplied_key2 contain untrusted data (that is, data which has not been validated):

let query = Select(from: confidential)
  .where(confidential.key1 == supplied_key1 || confidential.key2 == supplied_key2)

connection.execute(query: query) { queryResult in
  ...
}

To guard against SQL Injection attacks, use the following parameterized version of the code:

let query = Select(from: confidential)
  .where(confidential.key1 == Parameter() || confidential.key2 == Parameter())

connection.execute(query: query, parameters: supplied_key1, supplied_key2) { queryResult in
  ...
}

Prepared Statements

If your application executes the same (or similar) SQL statements repeatedly with different parameters you may improve the performance of the application by using a prepared statement. Prepared statements can reduce parsing time as the database parses and compiles the statement template only once and then stores the result but doesn’t execute it. Later, the application supplies values for the parameters of the statement template and the database executes the statement.

For example, suppose our application needs to retrieve the average grade for courses with an average above a given value; a value which we want to vary. Let’s change our query to use a parameter instead of a predefined value:

let query = Select(grades.course, round(avg(grades.grade), to: 1).as("average"), from: grades)
            .group(by: grades.course)
            .having(avg(grades.grade) > Parameter())
            .order(by: .ASC(avg(grades.grade)))

Now, prepare the statement:

do {
   let preparedStatement = try connection.prepareStatement(query)
}
catch {
   // Error.
}

Note: preparedStatement is a plugin-specific handle for the prepared statement.

Now the application may execute the prepared statement as many times as it wants with different parameter values:

connection.execute(preparedStatement: preparedStatement, parameters: [70]) { result in
   ...
}

Use the release function to free the prepared statement:

connection.release(preparedStatement: preparedStatement) { result in
  ...
}

Schema Management

Table creation

Swift-Kuery enables you to create tables on the database server.

Let’s revisit the Grades table, which we used in our Example above:

class Grades: Table {
    let tableName = "Grades"
    let id = Column("id", Int32.self, primaryKey: true)
    let course = Column("course", String.self)
    let grade = Column("grade", Int32.self)
}

We will add a second table called courses:

class Courses: Table {
    let tableName = "Courses"
    let name = Column("name", String.self, primaryKey: true)
    let credit = Column("credit", Int32.self)
    let teacher = Column("teacher", String.self)
}
let courses = Courses()

We can add a foreign key to Grades that references a column in another table:

let grades = Grades().foreignKey(grades.course, references: courses.name)

Create a multi-column primary key (if not set in the column as for Grades.id)

grades.primaryKey(grades.id, grades.course)

Create the table in the database:


courses.create(connection: connection) { result in
     guard result.success else {
        print("Failed to create table: \(result.asError?)")
     }
    ...
}

Indices

You can manage indices with Swift-Kuery in the following way:

let index = Index("index", on: grades, columns: [grades.id, desc(grades.grade)])
index.create(connection: connection) { result in ... }
...
index.drop(connection: connection) { result in ... }

Migration

Swift-Kuery has a class Migration to help with migrations between two versions of a table.

Suppose we have a table MyTable in our application. 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"
}

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

You can also execute raw alterations, if needed:

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

Query Examples

In the following section, we will provide an example SQL query and show you how to build and execute the same query in Swift using Swift-Kuery.

Classes used in the examples:

These examples we will use the following two tables:

class T1 {
  let tableName = "t1"
  let a = Column("a")
  let b = Column("b")
}

class T2 {
  let tableName = "t2"
  let c = Column("c")
  let b = Column("b")
}

 

SELECT * FROM t1;

This query will select all results from the table. The example below shows this how to execute this query including the boilerplate code:

let t1 = T1()

let query = Select(from: t1)

guard let connection = pool.getConnection() else {
   // Error
}

query.execute(connection) { queryResult in
  if let resultSet = queryResult.asResultSet {
    for title in resultSet.titles {
      // Process titles
    }
    for row in resultSet.rows {
      for value in row {
        // Process rows
      }
    }
  }
  else if let queryError = queryResult.asError {
    // process error
  }
}

The following examples show more complex queries, which can be substituted into the the above boilerplate.  

SELECT a, b FROM t1
WHERE (a LIKE ‘%b’ OR a = ‘apple’) AND b > 5
ORDER BY b ASC, a DESC
OFFSET 5;

let query = Select(t1.a, t1.b, from: t1)
  .where((t1.a.like("b%") || t1.a == "apple") && t1.b > 5)
  .order(by: .ASC(t1.b), .DESC(t1.a))
  .offset(5)

 

SELECT UCASE(a) AS name FROM t1
WHERE b >= 0
GROUP BY a
HAVING SUM(b) > 3
ORDER BY a DESC;

let query = Select(ucase(t1.a).as("name"), from: t1)
  .where(t1.b >= 0)
  .group(by: t1.a)
  .having(sum(t1.b) > 3)
  .order(by: .DESC(t1.a))

 

INSERT INTO t1
VALUES (‘apple’, 10), (‘apricot’, 3), (‘banana’, 17);

let query = Insert(into: t1, rows: [["apple", 10], ["apricot", 3], ["banana", 17]])

 

INSERT INTO t1
VALUES (‘apple’, 10);

let query = Insert(into: t1, values: "apple", 10)

 

INSERT INTO t1 (a, b)
VALUES (‘apricot’, ‘3’);

let query = Insert(into: t1, valueTuples: (t1.a, "apricot"), (t1.b, "3"))

 

INSERT INTO t1 (a, b)
VALUES (‘apricot’, ‘3’);

let query = Insert(into: t1, columns: [t1.a, t1.b], values: ["apricot", 3])

 

UPDATE t1 SET a = ‘peach’, b = 2
WHERE a = ‘banana’;

let query = Update(t1, set: [(t1.a, "peach"), (t1.b, 2)])
  .where(t1.a == "banana")

 

SELECT * FROM t1 AS left
LEFT JOIN t2 AS right
ON left.b = right.b;

let t1 = T1()
let t2 = T2()

let leftTable = t1.as("left")
let rightTable = t2.as("right")
let query = Select(from: leftTable)
  .leftJoin(rightTable)
  .on(leftTable.b == rightTable.b)

 

SELECT * FROM t1
JOIN t2
USING (b);

let query = Select(from: t1)
  .join(t2)
  .using(t1.b)

 

Queries with parameters:

Note: Named parameters are supported for all databases, even for those that do not support named parameters (e.g. PostgreSQL).

INSERT INTO t1
VALUES (@0,@1);

let query = Insert(into: t1, values: Parameter(), Parameter())

connection.execute(query: query, parameters: "banana", 28) { queryResult in
  // Process result
}

 

INSERT INTO t1
VALUES (@fruit,@number);

let query = Insert(into: t1, values: Parameter("fruit"), Parameter("number"))

connection.execute(query: query, parameters: ["number" : 28, "fruit" : "banana"]) { queryResult in
  // Process result
}

 

It is possible to insert NULL values using parameters:  

connection.execute(query: query, parameters: ["number" : 28, "fruit" : nil]) { queryResult in
  // Process result
}

 

Raw query:

connection.execute("CREATE TABLE myTable (a varchar(40), b integer)") {  queryResult in
  // Process result
}

 

SELECT LEFT(a, 2) as raw FROM t1
WHERE b >= 0 GROUP BY a
HAVING sum(b) > 3
ORDER BY a DESC;

let query = Select(RawField("LEFT(a, 2) as raw"), from: t1)
  .where("b >= 0")
  .group(by: t1.a)
  .having("sum(b) > 3")
  .order(by: .DESC(t1.a))

 

SELECT * FROM t1
WHERE b >= ANY (SELECT b FROM t2);

let query = Select(from: t1)
  .where(t1.b >= any(Select(t2.b, from: t2)))

 

SELECT * FROM t1
WHERE NOT EXISTS (SELECT * FROM t2 WHERE b < 8);

let query = Select(from: t1)
  .where(notExists(Select(from: t2).where(t2.b < 8)))

 

SELECT c FROM t2 GROUP BY c
HAVING SUM(b) NOT IN (SELECT b FROM t1 WHERE a = ‘apple’);

let query = Select(t2.c, from: t2)
    .group(by: t2.c)
    .having(sum(t2.b).notIn(Select(t1.b, from: t1).where(t1.a == "apple")))

List of plugins:

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.