:warning: NO LONGER MAINTAINED :warning:

This library is end-of-life and no longer supported.

This repository will not be updated. The repository will be kept available in read-only mode. If you are interested in continuing development efforts please see the list of forks for alternatives (e.g. #465).

For FAQs and additional information please refer to the Cloudant blog.

CDTDatastore

Applications use Cloudant Sync to store, index and query local JSON data on a device and to synchronise data between many devices. Synchronisation is under the control of the application, rather than being controlled by the underlying system. Conflicts are also easy to manage and resolve, either on the local device or in the remote database.

Cloudant Sync is an Apache CouchDB™ replication-protocol-compatible datastore for devices that don't want or need to run a full CouchDB instance. It's built by Cloudant, building on the work of many others, and is available under the Apache 2.0 licence.

The API is quite different from CouchDB's; we retain the MVCC data model but not the HTTP-centric API.

This library is for iOS, an Android version is also available.

If you have questions, please join our mailing list and drop us a line.

Using in your project

CDTDatastore is available through CocoaPods, to install it add the following line to your Podfile:

pod "CDTDatastore"

Note: We only support building on the latest stable release of Xcode

Using in a Swift app

CDTDatastore is useable from Swift out of the box with a few small quirks. Install as per the instructions above, and import CloudantSync.h into your bridging header.

The Overview section below has examples in both Objective-C and Swift.

Example project

There is an example project in the Project folder, for iOS 8.0. To get this up and running independently of the main codebase, a Podfile is included:

$ cd Project
$ pod install
$ open Project.xcworkspace

In order to run the sample project, edit the URL defined in CDTViewController.m: in replicatorURL. Change this to the credentials for your own account and database, ensuring you have _reader, _writer, and _replicator permissions.

Once running you will be able to edit "to-do" items in the app and in your Cloudant database and replicate these changes in both directions.

Running the tests

See CONTRIBUTING.

Tested Platforms

CDTDatastore gets regularly tested on the following platforms:

• OS X 10.11 (El Captain)
• iPhone 4S (Simulator), iOS 9.2

<a name="overview"></a>Overview of the library

Once the libraries are added to a project, the basics of adding and reading a document are:

#import <CloudantSync.h>

// Create a CDTDatastoreManager using application internal storage path
NSError *outError = nil;
NSFileManager *fileManager= [NSFileManager defaultManager];

NSURL *documentsDir = [[fileManager URLsForDirectory:NSDocumentDirectory
                                           inDomains:NSUserDomainMask] lastObject];
NSURL *storeURL = [documentsDir URLByAppendingPathComponent:@"cloudant-sync-datastore"];
NSString *path = [storeURL path];

CDTDatastoreManager *manager =
[[CDTDatastoreManager alloc] initWithDirectory:path
                                         error:&outError];

CDTDatastore *datastore = [manager datastoreNamed:@"my_datastore"
                                            error:&outError];

// Create a document
CDTDocumentRevision *rev = [CDTDocumentRevision revisionWithDocId:@"doc1"];
// Use [CDTDocumentRevision revision] to get an ID generated for you on saving
rev.body = [@{
    @"description": @"Buy milk",
    @"completed": @NO,
    @"type": @"com.cloudant.sync.example.task"
} mutableCopy];

// Add an attachment -- binary data like a JPEG
CDTUnsavedFileAttachment *att1 = [[CDTUnsavedFileAttachment alloc]
                          initWithPath:@"/path/to/image.jpg"
                          name:@"cute_cat.jpg"
                          type:@"image/jpeg"];
rev.attachments[att1.name] = att;

// Save the document to the database
CDTDocumentRevision *revision = [datastore createDocumentFromRevision:rev
                                                                error:&error];
// `revision` will be `nil` on failures.

// Read a document
NSString *docId = revision.docId;
CDTDocumentRevision *retrieved = [datastore getDocumentWithId:docId
                                                        error:&error];

If you are using Swift, install the library as per the instructions above and add the use_frameworks! instruction to your target. A bridging header is required if the use_frameworks! instruction is not used.

If you are using a bridging header, include the CloudantSync.h and you should be good to go:

#import <CDTDatastore/CloudantSync.h>

To add, and read documents in Swift, the basics are:

import CDTDatastore

do {
    let fileManager = FileManager.default

    let documentsDir = fileManager.urls(for: .documentDirectory, in: .userDomainMask).last!

    let storeURL = documentsDir.appendingPathComponent("cloudant-sync-datastore")
    let path = storeURL.path

    let manager = try CDTDatastoreManager(directory: path)
    let datastore = try manager.datastoreNamed("my_datastore")

    // Create a document
    let rev = CDTDocumentRevision(docId: "doc1")
    rev.body = ["description":"Buy Milk",
                "completed": false,
                "type":"com.cloudant.sync.example.task"]

    // Add an attachment - binary data like a JPEG
    let att1 = CDTUnsavedFileAttachment(path: "/path/to/image/jpg",
                                        name: "cute_cat.jpg",
                                        type: "image/jpeg")!
    rev.attachments[att1.name] = att1

    let revision = try datastore.createDocument(from: rev)

    // Read a document
    let docId = revision.docId
    let retrieved = try datastore.getDocumentWithId(docId!)

} catch {
    print("Encountered an error: \(error)")
}

Read more in the CRUD document.

You can subscribe for notifications of changes in the database, which is described in the events documentation. It's still a bit raw right now:

• You receive a notification for all new revisions in replication (which can be more than one per updated document).

Replicating Data Between Many Devices

Replication is used to synchronise data between the local datastore and a remote database, either a CouchDB instance or a Cloudant database. Many datastores can replicate with the same remote database, meaning that cross-device synchronisation is achieved by setting up replications from each device to the remote database.

Replication is simple to get started in the common cases:

#import <CloudantSync.h>

// Create and start the replicator -- -start is essential!
CDTReplicatorFactory *replicatorFactory =
[[CDTReplicatorFactory alloc] initWithDatastoreManager:manager];

NSString *s = @"https://apikey:apipassword@username.cloudant.com/my_database";
NSURL *remoteDatabaseURL = [NSURL URLWithString:s];
CDTDatastore *datastore = [manager datastoreNamed:@"my_datastore"];

// Replicate from the local to remote database
CDTPushReplication *pushReplication = [CDTPushReplication replicationWithSource:datastore
                                                                         target:remoteDatabaseURL];
NSError *error;
CDTReplicator *replicator = [replicatorFactory oneWay:pushReplication error:&error];

//check error

// Start the replicator
[replicator start];

import CDTDatastore
do {

    let datastore = try manager.datastoreNamed("my_datastore");

    // Replicate from the local to remote database
    let remote = URL(string: "https://apikey:apipassword@username.cloudant.com/my_database")!
    datastore.push(to: remote) { error in

        if let error = error {
            print("Encountered an error: \(error)")
        } else {
            print("Replication complete")
        }

    }

} catch {
    print("Encountered an error: \(error)")
}

Read more in the replication docs including how to use IAM authentication instead of username/password.

Finding data

Once you have thousands of documents in a database, it's important to have efficient ways of finding them. We've added an easy-to-use querying API. Once the appropriate indexes are set up, querying is as follows:

NSDictionary *query = @{
    @"name": @"John",         // name equals John
    @"age": @{ @"$gt" : @25}  // age greater than 25
};
CDTQResultSet *result = [datastore find:query];
[result enumerateObjectsUsingBlock:^(CDTDocumentRevision *rev,