README.md

Squeal, a Swift interface to SQLite

Squeal provides access to SQLite databases in Swift. Its goal is to provide a simple and straight-forward base API, allowing developers to build on top in ways that make sense for their apps. The API provides direct SQL access, as well as a complete set of helpers to reduce SQL drudgery. It's not a goal of this project to hide SQL from the developer, or to provide a generic object-mapping on top of SQLite.

Features

• Small, straightforward Swift interface for accessing SQLite databases via SQL.
• Helper methods for most common types of SQL statements.
• Easy database schema versioning and migration DSL.
• Simple DatabasePool implementation for concurrent access to a database.

Basic Usage

import Squeal

let db = Database()

// Create:
try db.createTable("contacts", definitions: [
    "id INTEGER PRIMARY KEY",
    "name TEXT",
    "email TEXT NOT NULL"
])

// Insert:
let contactId = try db.insertInto(
    "contacts",
    values: [
        "name": "Amelia Grey",
        "email": "[email protected]"
    ]
)

// Select:
struct Contact {
    let id:Int
    let name:String?
    let email:String
    
    init(row:Statement) throws {
        id = row.intValue("id") ?? 0
        name = row.stringValue("name")
        email = row.stringValue("email") ?? ""
    }
}

let contacts:[Contact] = try db.selectFrom(
    "contacts",
    whereExpr:"name IS NOT NULL",
    block: Contact.init
)

// Count:
let numberOfContacts = try db.countFrom("contacts")

The above example can be found in Squeal.playground to allow further exploration of Squeal's interface.

Migrations

Any non-trivial app will need to change its database schema as features are added or updated. Unfortunately, SQLite provides only minimal support for updating a database's schema. Things like removing a column or removing a NON NULL require the entire database to be re-created with the new schema.

Squeal makes migrations easy by including a Schema class with a simple DSL for declaring your database migrations. Once defined, the Schema can be used to migrate your database to the latest version.

Here's an example:

import Squeal

// Define a Schema:
let AppSchema = Schema(identifier:"contacts") { schema in
    // Version 1:
    schema.version(1) { v1 in
        // Create a Table:
        v1.createTable("contacts") { contacts in
            contacts.primaryKey("id")
            contacts.column("name", type:.Text)
            contacts.column("email", type:.Text, constraints:["NOT NULL"])
        }

        // Add an index
        v1.createIndex(
            "contacts_email",
            on: "contacts",
            columns: [ "email" ]
        )
    }
    
    // Version 2:
    schema.version(2) { v2 in        
        // Arbitrary SQL:
        v2.execute { db in
            try db.deleteFrom("contacts", whereExpr: "name IS NULL")
        }        
        // Tables can be altered in many ways.
        v2.alterTable("contacts") { contacts in
            contacts.alterColumn(
                "name",
                setConstraints: [ "NOT NULL" ]
            )
            contacts.addColumn("url", type: .Text)            
        }
    }
}

let db = Database()

// Migrate to the latest version:
let didMigrate = try AppSchema.migrate(db)

// Get the database version:
let migratedVersion = try db.queryUserVersionNumber()

// Reset the database:
try AppSchema.migrate(db, toVersion: 0)

The above example can be found in Migrations.playground.

Installation

Squeal can be installed via Carthage or CocoaPods.

Carthage

To install using Carthage, simply add the following line to your Cartfile:

github "nerdyc/Squeal"

CocoaPods

To install using Carthage, simply add the following to the appropriate target in your Podfile:

pod "Squeal"

License

Squeal is released under the MIT License. Details are in the LICENSE.txt file in the project.

Contributing

Contributions and suggestions are very welcome! No contribution is too small. Squeal (like Swift) is still evolving and feedback from the community is appreciated. Open an Issue, or submit a pull request!

The main requirement is for new code to be tested. Nobody appreciates bugs in their database.