Couchbase Mobile 1.2: Enabling ForestDB for iOS and Android

Couchbase Mobile 1.2

The new release of Couchbase Mobile 1.2, now available for download, delivers significant improvements around performance on the local client side storage engine for mobile devices. More specifically, the latest integration of ForestDB as the new storage engine designed to support various server and mobile operating systems. On the server side,Couchbase Server 4.1 completes the mobile story withSync Gateway 1.2 running in between the Couchbase Lite 1.2 mobile client. In this blog, I will explore ForestDB, examine the benefits, and share how developers can enable this feature in their apps.

ForestDB

What ForestDB provides for Couchbase Lite is a persistent key-value storage library where both the key and value mapping are binary blobs. ForestDB is a low-level key/value storage engine, and in the same family as Berkeley DB and LevelDB. As a developer you are able to get and set values accordingly as well as enumerate the keys in lexicographic order.

To better understand and find out more about the next generation storage engine for Couchbase, view this presentation by Chiyoung Seo at the 2015 Couchbase Connect:

Benefits

Here are some of the performance improvements of the new storage system for Couchbase Lite 1.2:

• Faster speed — this will vary by app, but we’ve seen from 2x to 5x improvement in tasks like document insertion and querying.
• Better concurrency — a writer thread (like the replicator) never blocks readers (like your GUI thread.) This helps keep your application responsive.
• Lower RAM footprint — data caches are shared between threads, reducing the overhead of having multiple threads access a database, as occurs during replication.
• Auto Database compaction — Database compaction (which frees up disk space) runs in the background without blocking other threads, and is scheduled automatically whenever there’s enough space to recover.

Depending on the operation and data set involved, there can be up to 5X improvement in speed, as well as, better concurrency management where the writer never blocks the readers. Because data caches are shared between threads, we now see a lower RAM footprint. This is complimented by automatic database compaction and background presence. You can read more about the ForestDB benchmarks and performance testing results by visiting Cihan Biyikoglu’s blog on the next generation storage engine for Couchbase Server and Couchbase Lite.

Get Started

In previous versions, SQLite was the available storage engine for Coucbase Lite. While SQLite currently emains the default, for Couchbase Mobile 1.2 there is an optional package in the Couchbase Lite project library to enable ForestDB. The iOS and Android GrocerySync starter project with ForestDB components can be downloaded from GitHub on the specific branch.

Enable ForestDB

Now I’m going to discuss how to enable ForestDB inside our mobile application projects to take advantage of the new benefits. Note that if you have a previous project using an earlier version of Couchbase Lite then the existing database files are not converted. This is where a SQLite-backed database will continue using SQLite by default because the format of the database type is established at the beginning of project creation. The existing database will always open with the same storage engine that created them. Stay tuned for future blogs that will address how to migrate that over.

iOS:

The following describes the steps required to enable the ForestDB storage engine from within your iOS project. First move or copy the ‘CouchbaseLite.framework’ library file found from the couchbase-lite-ios-enterprise_1.2.0-112 ZIP file into your iOS app project’s folder or into your iOS app project’s Frameworks subfolder. From there, drag the version 1.2 CouchbaseLite.framework into the project to avoid creating a reference in your project to some other filesystem path. This allows the framework to be available on all machines.

The Frameworks folder should now contain the CouchbaseLite.framework file. Next, drag in the libCBLForestDBStorage.a file so that both the green highlights are available in your Frameworks folder.

The system library libc++dylib needs to be linked and to do that we will go into the target’s “Build Phases” editor. Click on the ‘+’ symbol under the “Link Binary with Libraries” section and select the file of interest from ‘/usr/lib/’ or simply type ‘c++’ into the filter field in the library chooser and ‘libc++’ will show up.

The file path may look similar to the following:

• In Xcode, open the Build Phases screen of your application target, and open the Link Binary With Libraries section.
• Drag libCBLForestDBStorage.a from the filesystem folder (where you dragged it to, earlier) into the list in the Link Binary With Libraries section.
• Click on the ‘+’ symbol under the list of libraries to open the library chooser. Type ‘c++’ into the filter field, and ‘libc++’ will show up. Select it and add it.

• Now build your project; it should succeed.

ForestDB is now available, but it isn’t set as the default storage type, so new databases will still be created with SQLite. To change this, set the CBLManager instance’s storageType property before opening any databases.  For example, you might add the code outlined in green:

Upon which the CBLManager class may be referenced to specify the ‘storageType’ property to be ForestDB.  This is how we enable the iOS project to use now the ForestDB storage system.

For the specific sample app project, navigate to your ‘AppDelegate.m’ file and under the ‘createDatabase’ method, specify the storageType property.  But typically this depends on your app code’s structure and is usually in the application delegate class.  Go to the place in your project or code where you instantiate the CBLManager class, and right afterwards add a line to set its storageType property, like so:

Now we are ready to build and run the application to have our mobile app use ForestDB as the storage engine.

Android:

Here are the steps required to enable the ForestDB store from within your Android project.

From within your Android project, the module level’s build.gradle file would need to reference Couchbase Lite version 1.2 along with explicitly bringing in ForestDB as a storage engine at the dependency level. The dependencies would now include:

And overall the build.gradle file should look like:

You may reference the build.gradle file from GitHub.  Now over in our ‘MainActivity.java’ file, what is new in Couchbase Lite 1.2 for Android is that there is now the ‘DatabaseOptions’ class where we specify the properties like ‘.setStorageType’.

To enable ForestDB in our Android application, we now need to pass in the ForestDB_Storage parameter to the ‘setStorageType’ function to switch the storage type from SQLite to ForestDB.  See below to learn how this is done:

Below in the GrocerySync sample app, we see where we reference the ‘setStorageType’ property from within the startCBLite() method:

So there you have it, Couchbase Mobile 1.2 comes with ForestDB as the new storage engine and we learned how to enable the feature from the default SQLite solution. We will explore Couchbase Mobile 1.2 further, including encryption and performance topics in follow-up blogs.  Be sure to download the new Couchbase Mobile 1.2 and connect with us in our Mobile Developer Forums.