Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
a key-value object store backed by sqlite3 for ios
Objective-C Ruby
branch: master

README.md

Warning: this package is not actively supported.

You may prefer to use something newer like Couchbase Lite, which is excellent and is widely supported. This package was made long before NoSQL was really available on iPhone.

kvdb

kvdb is a key-value store for iOS backed by SQLite3.

It can serialize and store any objects that implement the NSCoding protocol.

Therefore, lots of objects are supported right away:

  • NSDictionary
  • NSArray
  • NSNumber
  • NSString

etc.

Usage

#import "kvdb.h"

[[KVDB sharedDB] setValue:@"apple" forKey:@"fruit"];
[[KVDB sharedDB] setValue:@"Chicago" forKey:@"city"];

MyObject *object = [[MyObject alloc] initWithTitle:@"KVDB"];
[[KVDB sharedDB] setValue:object forKey:@"my_object"];

Installation

The recommended way is to install via Cocoapods:

Add into your Podfile:

pod 'kvdb', :git => 'https://github.com/colinyoung/kvdb'

And run

pod update

or you can just clone kvdb and add kvdb/ folder to your project.

Other stuff

[[KVDB sharedDB] dropDatabase];

[[KVDB sharedDB] createDatabase];

// Instantiate w/ a different file:
[KVDB sharedDBWithFile:@"blah.sqlite3"]; // the file will be created in your documents directory.

Coding nil-values: nil vs NSNull

To provide a compatibility with NSArray and NSDictionary classes KVDB denies the coding of nil values. KVDB follows the same policy as NSDictionary class does:

-[KVDB setValue:forKey:] - if value is nil then method attempts to remove key using removeValueForKey:.

-[KVDB setObject:forKey:] - raises an NSInvalidArgumentException if aKey is nil.

Like it is done when working with instances of NSArray or NSDictionary use NSNull class whereever you want -[KVDB setValue:forKey] to provide a given key with a null value:

Use

[[KVDB sharedDB] setValue:[NSNull null] forKey:@"fruit"];

id dbValue = [[KVDB sharedDB] valueForKey:testKey]; 

NSLog(@"%@", dbValue); // will print "<null>" i.e.  NSNull singleton

Instead of

[[KVDB sharedDB] setObject:nil forKey:@"fruit"]; // => Results in NSInvalidArgumentException

or

[[KVDB sharedDB] setValue:nil forKey:@"fruit"]; // => Results in removeValueForKey: behavior 

See the documentation of -[NSDictionary setObject:forKey:] and this nice NSHipster article about nil and NSNull.

Notes

  • kvdb is a simple key value store for iOS solution with codebase containing just a couple of files. Don't ask it what it is not intended for: it is not thread-safe, it does not support transactions and so on. For more serious solutions see "Similar tools".
  • kvdb plays very nice with all the solutions like Mantle, which provide auto-coding for all the properties you declare in your classes. For example, if using Mantle: create a MTLModel subclass, declare its properties, and... it is ready to be stored in a KVDB store, because Mantle has already autocoded these properties for you.

Similar tools

Copyright

Copyright (c) 2012 Colin Young. See LICENSE for details.

Something went wrong with that request. Please try again.