a key-value object store backed by sqlite3 for ios
Objective-C Ruby
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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 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



#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"];


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:


[[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


[[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.


  • 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 (c) 2012 Colin Young. See LICENSE for details.