A type safe MySQL client for Swift
Swift Objective-C Makefile
Latest commit c1d7b8c Dec 15, 2016 @novi committed on GitHub Merge pull request #47 from novi/minor-renaming
Minor renaming

README.md

mysql-swift

Swift 3.0 Platform Linux, macOS Carthage compatible Build Status

MySQL client library for Swift. This is inspired by Node.js' mysql and Himotoki as decoding results.

  • Based on libmysqlclient
  • Raw SQL query
  • Simple query formatting and escaping (same as Node's)
  • Decoding and mapping queried results to Swift struct or class

Note: No asynchronous support currently. It depends libmysqlclient.

// Declare a model

struct User: QueryRowResultType, QueryParameterDictionaryType {
    let id: Int
    let userName: String
    let age: Int?
    let status: Status
    let createdAt: Date

    enum Status: String, SQLEnumType {
        case created = "created"
        case verified = "verified"
    }

    // Decode query results (selecting rows) to a model
    static func decodeRow(r: QueryRowResult) throws -> User {
        return try User(
            id: r <| 0, // as index
            userName: r <| "name", // as field name
            age: r <|? 3, // nullable field,
            status: r <| "status", // string enum type
            createdAt: r <| "created_at"
        )
    }

    // Use this model as a query paramter
    // See inserting example
    func queryParameter() throws -> QueryDictionary {
        return QueryDictionary([
            //"id": // auto increment
            "name": userName,
            "age": age,
            "status": status,
            "created_at": createdAt
        ])
    }
}

// Selecting
let nameParam: String = "some one"
let ids: [QueryParameter] = [1, 2, 3, 4, 5, 6]
let optional:Int? = nil
let params: (Int, Int?, String, QueryArray) = (
    50,
    optional,
    nameParam,
    QueryArray(ids)
)   
let rows: [User] = try conn.query("SELECT id,name,created_at,age FROM users WHERE (age > ? OR age is ?) OR name = ? OR id IN (?)", build(params) ])

// Inserting
let age: Int? = 26
let user = User(id: 0, userName: "novi", age: age, createdAt: Date())
let status = try conn.query("INSERT INTO users SET ?", [user]) as QueryStatus
let newId = status.insertedId

// Updating
let defaultAge = 30
try conn.query("UPDATE users SET age = ? WHERE age is NULL;", [defaultAge])

Requirements

  • Swift 3 (development snapshot)

Dependencies

  • MariaDB Connector/C (libmysqlclient) 2.2.3

OS X

  • Install mariadb(includes libmysqlclient).
$ brew install mariadb

Ubuntu Linux

$ sudo apt-get install libmariadbclient-dev

Installation

Swift Package Manager

  • Add mysql-swift to Package.swift of your project.
import PackageDescription

let package = Package(
    dependencies: [
        .Package(url: "https://github.com/novi/mysql-swift.git", majorVersion: 0)
    ]
)

Note: You may need to specify library path for libmysqlclient to link with.

# Linux
swift build -Xlinker -L/usr/lib
# OS X 
swift build -Xlinker -L/usr/local/lib -Xcc -I/usr/local/include -Xcc -I/usr/local/include/mysql

Usage

Connection & Querying

  1. Create a pool with options (hostname, port, password,...).
  2. Get a connection from the pool.
  3. Execute query and fetch rows or status.
  4. Back the connection to the pool (call release()),
    let options = Options(host: "your.mysql.host"...)
    let pool = ConnectionPool(options: options) // Create a pool with options

    let conn = try pool.getConnection() // Get free connection
    conn.query("SELECT 1 + 2;")
    conn.release() // Release and back connection to the pool

or You can just use pool.execute(). It automatically get and release a connection.

    let rows: [User] = try pool.execute { conn in
        // The connection is held in this block
        try conn.query("SELECT * FROM users;") // And it returns result to outside execute block
    }

Transaction

    let options = Options(host: "your.mysql.host"...)
    let pool = ConnectionPool(options: options) // Create pool with options

    let wholeStaus: QueryStatus = try pool.transaction { conn in
        let status = try conn.query("INSERT INTO users SET ?;", [user]) as QueryStatus // Create a user
        let userId = status.insertedId // the user's id
        try conn.query("UPDATE info SET val = ? WHERE key = 'latest_user_id' ", [userId]) // Store user's id that we have created the above
    }
    wholeStaus.affectedRows == 1 // true

License

MIT