There are many libraries out there that aims to help developers easily create and use SQLite databases. Unfortunately developers still have to get bogged down in simple tasks such as writing table definitions and SQL queries. SwiftyDB automatically handles everything you don't want to spend your time doing.

Content

Features

Usage

Access the database

Synchronous access

Add or update data

Retrieve data

Retrieve objects

Delete data

Aynchronous access

Add or update data

Retrieve data

Retrieve objects

Delete data

Result format

Handling results

Handling values

Handling errors

Filter results

Simple filters

Complex filters

Defining your classes

Primary keys

Ignoring properties

How to retrieve objects

Installation

License

[x] Creates and updates databases, tables, and records automatically

[x] Store any native Swift type

[x] Supports optional types

[x] Simple equality-based filtering

[x] Thread safe database operations

[x] Supports asynchronous database access

[x] 100% documented

[x] Complex filtering

[ ] Store nested objects

[ ] Store collections

Almost pure plug and play. All you have to do is create an instance of SwiftyDB, and everything will be handled automagically behind the scenes 🎩

Tell SwiftyDB what you want to call your database, and you are ready to go. If a database with the provided name does not exist, it will be created.

let database = SwiftyDB(databaseName: " dogtopia " )

database . addObject(dog, update: true ) database . addObjects(dogs, update: true )

Retrieve data with datatypes matching those of the type's properties

/* Array of dictionaries representing `Dog` objects from the database */ database . dataForType(Dog . self ) database . dataForType(Dog . self , matchingFilters: [ " id " : 1 ])

Dog data example

[ " id " : 1 , // As an Int " name " : " Ghost " , // As a String " owner " : " John Snow " , // As a String " birth " : August 6 , 1996 // As an NSDate ]

Retrieve objects with data from the database

database . objectsForType(Dog . self ) database . objectsForType(Dog . self , matchingFilters: [ " id " : 1 ])

In order to retrieve objects, Swift currently imposes some restictions on your classes

database . deleteObjectsForType(Dog . self ) database . deleteObjectsForType(Dog . self , matchingFilters: [ " name " : " Max " ])

database . asyncAddObject(dog) { (result) -> Void in if let error = result . error { // Handle error } }

Retrieve data with datatypes matching those of the type's properties

database . asyncDataForType(Dog . self ) { (result) -> Void in if let data = result . value { // Process data } }

Retrieve data with datatypes matching those of the type's properties

database . asyncObjectsForType(Dog . self ) { (result) -> Void in if let objects = result . value { // Handle objects } }

In order to retrieve objects, Swift currently imposes some restictions on your classes

database . asyncDeleteObjectsForType(Dog . self ) { (result) -> Void in if let error = result . error { // Handle error } }

Filter objects are used to filter queries. All filters are translated to SQLite before querying the database.

The easiest way to define your filter, is by using a dictionary:

database . objectsForType(Dog . self , matchingFilters: [ " name " : " Ghost " ])

All objects with the name 'Ghost' will be retrieved

For more complex filters, you can instantiate a new Filter object, and define your filters

let filter = Filter . equal( " name " , value: " Ghost " ) filter . like( " owner " , pattern: " J_h% " ) filter . greaterThan( " id " , value: 3 ) database . objectsForType(Dog . self , matchingFilters: filter)

You can also chain your filters

let filter = Filter . equal( " name " , value: " Ghost " ) . like( " owner " , pattern: " J_h% " ) . greaterThan( " id " , value: 3 ) database . objectsForType(Dog . self , matchingFilters: filter)

See all available filters in the documentation.

All queries returns the result as a Result . It will either be a .Success wrapping data from the query, or an .Error wrapping the thrown error.

enum Result < A: Any > : BooleanType { case Success(A) case Error( ErrorType ) var data: A? var error: ErrorType ? var isSuccess: Bool var boolValue: Bool { return isSuccess} }

The implementation of Result makes it a versatile tool that can (hopefully 😬 ) be adapted to your programming style

You can capture the data from a query with the value property. If an error was thrown, this property will be nil .

if let object = result . value { // Process objects }

You can detect an error like this

if ! database . addObject(dog) { // An error occured }

or capture it using the error property like this

if let error = result . error { // Process objects }

If you want to, you can even bring your sledgehammer and start cracking some nuts

switch result { case . Success( let value): // Process value case . Error( let error): // Handle error }

Let's use this simple Dog class as an example

class Dog { var id: Int ? var name: String ? var owner: String ? var birth: NSDate? }

All objects must conform to the Storable protocol.

public protocol Storable { init () }

By adding the Storable protocol and implementing init() , you are already ready to go.

class Dog: Storable { var id: Int ? var name: String ? var owner: String ? var birth: NSDate? required init () {} }

SwiftyDB supports inheritance. Valid properties from both the class and the superclass will be stored automatically

It is recommended to implement the PrimaryKeys protocol. The primaryKeys() method should return a set of property names which uniquely identifies an object.

extension Dog: PrimaryKeys { class func primaryKeys () -> Set < String > { return [ " id " ] } }

If your class contains properties that you don't want in your database, you can implement the IgnoredProperties protocol.

extension Dog: IgnoredProperties { class func ignoredProperties () -> Set < String > { return [ " name " ] } }

Properties with datatypes that are not part of the SQLiteValue protocol, as defined by TinySQLite, will automatically be ignored by SwiftyDB

SwiftyDB can also retrieve complete objects with all properties assigned with data from the database. In order to achieve this, the type must be a subclass of NSObject , and all property types must be representable in in Objective-C. This is because pure Swift currently does not support dynamic assignment of properties.

Dynamic property types

[x] Int

[x] UInt

[x] Float

[x] Double

[x] Bool

[x] String / String?

/ [x] NSNumber / NSNumber?

/ [x] NSString / NSString?

/ [x] NSDate / NSDate?

/ [x] NSData / NSData?

An updated Dog class that can be used to retrieve complete objects from the database:

class Dog: NSObject, Storable { var id: NSNumber? // Notice that 'Int?' is not supported. Use NSNumber? instead var name: String ? var owner: String ? var birth: NSDate? override required init () { super . init () } }

SwiftyDB is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod " SwiftyDB "

Author

Øyvind Grimnes, oyvindkg@yahoo.com

SwiftyDB is available under the MIT license. See the LICENSE file for more info.