Simplifying Persistence with a Document Database

Most application developers, when they realize the need for a persistent data store, will automatically reach for SQL. It’s a time-tested technology, after all, and one that most of us have been using for a long time. However, in many cases implementing a SQL database is overkill.  Fortunately, our Couchbase Lite component offers an alternative to SQL: the schemaless document database. 

Most apps don’t have lots of highly relational data; instead, they just need a place to shove some records in and pull some records back out, and sometimes link one record with some others. Despite these modest requirements, developers end up spending lots of time modeling their data in third normal form, writing DDL, and mapping their relational data to their objects and managing impedance mismatch. Schemaless document databases, like Couchbase Lite, do away with that. That’s why these kinds of databases have been tagged with the “NoSQL” moniker.

Instead of tables with rows, Couchbase Lite and their ilk store data in documents, which are essentially just JSON dictionaries. This makes it very easy to work with in code. The following code demonstrates how easy it is to create a new record:

// Create a new dictionary.
var vals = new NSMutableDictionary ();
// Add a bunch of key/value pairs.
vals ["text"] = (NSString)value;
vals ["check"] = NSNumber.FromBoolean(false);
vals ["created_at"] = (NSString)DateTime.UtcNow.ToString("o"); // ISO 8601 date/time

// Create a new database document.
var doc = Database.UntitledDocument;

NSError error;
// Save the values in the doc.
var result = doc.PutProperties (vals, out error);

As you can, there’s no conversion to a parameterized INSERT statement and no configuration of an ORM. Once the document’s properties are modified, the data is persisted locally. If later on I decide to add a new property to my objects, I just start including that new key/value pair to the dictionary I pass to PutProperties: vals ["new_prop"] = bar. There’s no need to run an ALTER TABLE query before INSERT. Older documents just won’t have that key defined.

Reading and updating values are also easy:

// Get an existing doc.
var doc = database.DocumentWithID ("05F4F796-2C16-4BD5-A592-B12EC501E0BB");
// Get our key/value pairs.
var vals = doc.Properties.MutableCopy() as NSMutableDictionary;
// Update an existing value.
vals ["check"] = NSNumber.FromBoolean (false);
// Add a new key/value pair.
vals ["new_prop"] = bar;

NSError error;
// Save a new version of the document.
doc.CurrentRevision.PutProperties (vals, out error);

Did I mention that most document stores version their documents? Couchbase Lite is no exception. It uses this revision history to handle merge conflicts. We will revisit this topic in our upcoming article on master-master replication.

Notice how we never include any “primary key”? Internally you will find a key named _id defined in every document. By default, Couchbase Lite will generate a globally unique identifier for you. If you prefer to use natural keys, however, you can pass in any unique string you like. We used this key to retrieve a document by its id in the first line of the update code example above. This value also gives us a way to refer to another document: vals ["other_doc"] = otherDoc.DocumentID. We will talk more about querying these relationships in an upcoming article on using MapReduce queries with Couchbase Lite.

Finally, deleting a doc is also quite easy:

var doc = database.DocumentWithID ("05F4F796-2C16-4BD5-A592-B12EC501E0BB");
NSError deleteError;
var isDeleted = doc.DeleteDocument (out deleteError));

This performs a logical delete, as will be evidenced by the document’s IsDeleted property. When you implement a MapReduce, you can take advantage of this property to remove these documents from your index. In our upcoming article on sync, we will also discuss why it’s important that this is a logical, not an immediate physical delete, from our data store.

Document databases really shine when querying, which is particularly important on mobile devices as users expect nearly instantaneous access to data.  We’ll explore the benefits of document databases more in on our upcoming article on Couchbase Lite’s MapReduce views.

Interested in learning more? Join Zack Gramana, Xamarin’s Technical Lead for the Component Store, and Wayne Carter, Architect at Couchbase for our upcoming webinar on October 10, at 8:00 AM PDT/11:00 AM EDT.

Register