sqlk /

Filename Size Date modified Message
Classes
SQLiteKit
Unit Testing (Mac)
Unit Testing (iOS)
fmdb [e347ea78af34]
sqlk.xcodeproj
218 B
66 B
1022 B
11.1 KB
5.3 KB
951 B

SQLite Kit

This SQLite kit aims to ease working with SQLite databases in Cocoa by providing :

  • An SQLiteObject, distantly related to NSManagedObject for CoreData
  • SQLK structures, easing database generation and updating from XML files

The kit tries to complement fmdb, the awesome SQLite Cocoa wrapper by Gus Mueller. The project uses ARC, so if you haven't yet moved to ARC you're on your own.

License

This project is released under the Apache 2.0 license, because why not. There is no NOTICE file so you don't need to mention anything when using the kit.

Setup

Here's one way on how you can use SQLiteKit for your app:

  1. Use git to clone the kit as a submodule (if you use git, otherwise just use git clone):

cd your-project git submodule add git://github.com/p2/sqlk.git

  1. Add the sqlk project to your Xcode workspace
  2. Go to your app's build settings and add this to your User Header Search Paths, with recursive enabled:

"$(PROJECT_DIR)"

  1. Go to your app's build phases and add these two frameworks:

libsqlite3.dylib libsqlk.a

Using SQLiteObject

For each table that you have, you create a subclass of SQLiteObject. You need to do at lest four things:

  • Add SQLiteKit.h and .m to your project and create a subclass
  • Add properties
  • Override +tableName
  • Override +tableKey

Adding Properties

You can add as many properties to the subclass as you'd like. To have the object recognize a property as one that is stored in the database, you synthesize that property to be the same name as the db variable plus an underscore at the end, for example:

@synthesize db_prop = db_prop_;

This makes the object automatically read and write the db_prop property from/to the database on hydrate: and dehydrate.

Overriding tableName and tableKey

You override these class methods to tell the objects to which table they belong, like so:

+ (NSString *)tableName
{
    return @"test_table";
}

+ (NSString *)tableKey
{
    return @"row_id";
}

Using SQLiteObject

After these three steps you can now use your objects easily:

Writing to the database

FMDatabase *db = [FMDatabase databaseWithPath:path-to-sqlite];
MyObject *obj = [MyObject newWithDatabase:db];
obj.db_prop = @"Hello World";

NSError *error = nil
if (![db dehydrate:&error]) {
    NSLog(@"Dehydrate failed: %@", [error localizedDescription]);
}

Reading from the database

FMDatabase *db = [FMDatabase databaseWithPath:path-to-sqlite];
MyObject *obj = [MyObject newWithDatabase:db];
obj.object_id = @1;

if (![db hydrate]) {
    NSLog(@"Hydrate failed");
}

Using the kit

The rest of the kit provides ways to create and update your SQLite database. it can read database structures from an XML file and create a database that represents this schema, and even update existing databases to match the schema, within the constraints of SQLite. Remember, SQLite can not rename or delete table columns.

XML Schema

Here's an example schema:

<database>
    <table name="objects">
        <column name="object_id" type="varchar" primary="1" />
        <column name="type" type="varchar" />
        <column name="title" type="varchar" default="None" quote_default="1" />
        <column name="year" type="int" />
        <column name="lastedit" type="timestamp" default="CURRENT_TIMESTAMP" />
        <constraint>UNIQUE (title, year) ON CONFLICT REPLACE</constraint>
    </table>
</database>

database

The XML root object, attributes are not parsed.

Children:

  • table

table

Describes one table.

Attributes:

  • name mandatory, any valid SQLite table name
  • old_names potentially. NOT IMPLEMENTED; could be a good way to rename tables

Children:

  • column
  • constraint

column

Describes one table column, doesn't take child nodes.

Attributes:

  • name mandatory, any valid SQLite column name
  • type mandatory, any valid SQLite data type
  • primary optional, a bool indicating whether this is the primary key
  • unique optional, a bool indicating whether this column should be unique
  • default optional, the column's default value
  • quote_default optional, a bool indicating whether the value in default needs to be put in quotes (i.e. is a string, not a SQLite variable)

constraint

Describes a table constraint. The node takes no attributes and the node content should be a valid SQLite constraint.

To do

A lot! If you like the project and want to help out, fork, fix and send me pull requests.

SQLiteObject

  • Support fetching sub-properties of many objects, e.g. for listing purposes. I currently do that with a +listQuery object that only fetches a few properties, having this built-in would be nice.

XML

  • Write an actual XSD
  • Support more SQLite features

Better column parsing (from .sqlite)

  • Correctly parse DEFAULT values (currently regards everything after DEFAULT until the next comma as default)
  • Parse ON CONFLICT statements for UNIQUE and PRIMARY KEY statements (are currently ignored)
  • Support COLLATE statements
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.