Using the Datastore API on iOS

These days, your app needs to store and sync more than just files. With the Datastore API, structured data like contacts, to-do items, and game state can be synced effortlessly. Datastores support multiple platforms, offline access, and automatic conflict resolution.

Here are the basic concepts that underlie the Datastore API:

Account manager and datastore manager
The account manager is your starting point. It lets your app start the authentication process to link with a user's Dropbox account. Once you've linked to an account, you can create a datastore manager, which you can use to open datastores, get a list of datastores, wait for changes to multiple datastores, and so on.
Datastores and tables

Datastores are containers for your app's data. Each datastore contains a set of tables, and each table is a collection of records. As you'd expect, the table allows you to query existing records or insert new ones.

A datastore is cached locally once it's opened, allowing for fast access and offline operation. Datastores are also the unit of transactions; changes to one datastore are committed independently from another datastore. After modifying a datastore, call the sync method to sync those changes back to Dropbox and also apply changes that may have been made by other devices.

Records

Records are how your app stores data. Each record consists of a set of fields, each with a name and a value. Values can be simple objects, like strings, integers, and booleans, or they can be lists of simple objects. A record has an ID and can have any number of fields.

Unlike in SQL, tables in datastores don't have a schema, so each record can have an arbitrary set of fields. While there's no requirement to have the same fields, it makes sense for all the records in a table to have roughly the same fields so you can query over them.

Now that you're familiar with the basics, read on to learn how to get the Datastore API running in your app.

Setting up the SDK

If you want to code along with this guide, start by visiting the SDKs page for instructions on downloading the SDK and setting up your project.

Linking accounts

To start using the Datastore API, you'll need to create a DBAccountManager object. This object lets you link to a Dropbox user's account, which is the first step to working with data on their behalf.

A good place to create this object is in your app delegate's -application:didFinishLaunchingWithOptions: method.

YourAppDelegate.m

Be sure to replace APP_KEY and APP_SECRET with the real values for your app which can be found in the App Console.

#import <Dropbox/Dropbox.h>

- (BOOL)application:(UIApplication *)app didFinishLaunchingWithOptions:(NSDictionary *)opts {
    DBAccountManager *accountManager =
        [[DBAccountManager alloc] initWithAppKey:@"APP_KEY" secret:@"APP_SECRET"];
    [DBAccountManager setSharedManager:accountManager];

    return YES;
}

The next step is to have the user start the linking flow (keep in mind, you'll need all the pieces in this section in place before it will work end-to-end). You can start the linking flow in response to a user action asking to link to Dropbox. This example will add a didPressLink IBAction to your view controller. You'll also need to connect it to a button in Interface Builder.

The Datastore API will automatically store the user's account info on the device once they've linked. You should check whether an account is already linked by calling linkedAccount.

Your view controller

- (IBAction)didPressLink {
    DBAccount *account = [[DBAccountManager sharedManager] linkedAccount];
    if (account) {
        NSLog(@"App already linked");
    } else {
        [[DBAccountManager sharedManager] linkFromController:self];
    }
}

The linking process will switch to the Dropbox mobile app if it's installed so the user doesn't need to log in again. Otherwise, a Dropbox authorization view will be presented from the specified view controller. Once the user completes the authorization step, Dropbox will redirect them back to your app using the URL scheme you registered when setting up the SDK. Your app needs to handle those requests to complete the auth flow.

YourAppDelegate.m

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url
    sourceApplication:(NSString *)source annotation:(id)annotation {
    DBAccount *account = [[DBAccountManager sharedManager] handleOpenURL:url];
    if (account) {
        NSLog(@"App linked successfully!");
        return YES;
    }
    return NO;
}

You now have all the pieces you need to link to a user's account. Run the app and press your Link to Dropbox button. Your app should proceed through the authorization flow and return to your app with the account associated with the account manager.

Creating a datastore and your first table

With a DBAccount in hand, the next step is to open the default datastore. Each app has its own default datastore per user. You should retain your datastore for as long as you need it to sync. In this example, we assume your class has @property (retain) DBDatastore *store.

DBAccount *account = [[DBAccountManager sharedManager] linkedAccount];
self.store = [DBDatastore openDefaultStoreForAccount:account error:nil];

In order to store records in a datastore, you'll need to put them in a table. Let's define a table named "tasks":

DBTable *tasksTbl = [self.store getTable:@"tasks"];

In the future, you might choose to add more tables to store related sets of things such as a "settings" table for the app or a "people" table to keep track of people assigned to each task. For now, this app is really simple so you only need one table to hold all your tasks.

You've got a datastore manager, a datastore for your app, and a table for all the tasks you're about to make. Let's start storing some data.

Working with records

A record is a set of name and value pairs called fields, similar in concept to a dictionary. Records in the same table can have different combinations of fields; there's no schema on the table which contains them. In fact, the record is created by first creating a dictionary.

DBRecord *firstTask = [tasksTbl insert:@{ @"taskname": @"Buy milk", @"completed": @NO }];

This task is now in memory, but hasn't been persisted to storage or synced to Dropbox. Thankfully, that's simple:

[self.store sync:nil];

Sync may be a straightforward method, but it wraps some powerful functionality. Sync both saves all of your local changes and applies any remote changes as well, automatically merging and dealing with conflicts along the way. Sync even works offline; you won't apply any remote changes, but your local changes will be saved to persistent storage and synced to Dropbox when the device comes back online.

Once syncing completes, visit the datastore browser and you should see your newly created task.

Accessing data from a record is straightforward:

NSString* taskname = firstTask[@"taskname"];

Editing tasks is just as easy. This is how you can mark the first result as completed:

firstTask[@"completed"] = @YES;
[self.store sync:nil];

After the edit, calling sync will commit the edits locally and then sync them to Dropbox.

Finally, if you want to remove the record completely, just call -deleteRecord().

[firstTask deleteRecord];
[self.store sync:nil];

Querying records

You can query the records in a table to get a subset of records that match a set of field names and values you specify. The query method takes a set of conditions that the fields of a record must match to be returned in the result set. For each included condition, all records must have a field with that name and that field's value must be exactly equal to the specified value. For strings, this is a case-sensitive comparison (e.g. "abc" won't match "ABC").

NSArray *results = [tasksTbl query:@{ @"completed": @NO } error:nil];
DBRecord *firstResult = [results objectAtIndex:0];

results is an array of DBRecord objects.

The records that meet the specified query are not returned in any guaranteed order. The entire result set is returned so you may apply sort in memory after the request completes.

If no condition set is provided, the query will return every record in the table.

NSArray *results = [tasksTbl query:nil error:nil];

Using observers

A datastore will receive changes from other instances of your app when you call sync. For some apps, the frequency of updates will be low; others may be rapid-fire. In either case, your app should respond as soon as those changes happen by updating the state of your app. You can do this by registering sync status observers.

__weak typeof(self) weakSelf = self;
[self.store addObserver:self block:^() {
    if (weakSelf.store.status & DBDatastoreIncoming) {
        NSDictionary *changes = [weakSelf.store sync:nil];
        // Handle the updated data
    }
}];

The observer's block is called whenever the status of the datastore changes, which includes downloading or uploading changes. It is also called when there are changes ready to be applied to the local state.

Checking self.store.status in the block lets you figure out when there are new changes that your app should respond to. If there are changes, calling sync will apply those changes to the datastore. sync will also return a dictionary of table IDs to sets of records that changed as a result of the sync. Your app can update based on the set of changed records or you can simply query the new states of the tables and update your app's views with the results.

Records and fields

The record is the smallest grouping of data in a datastore. It combines a set of fields to make a useful set of information within a table.

Record IDs

Each record has a string ID. An ID can be provided when a record is created, or one will be automatically generated and assigned if none is provided. Once a record is created, the ID cannot be changed.

Other records can refer to a given record by storing its ID. This is similar to the concept of a foreign key in SQL databases.

Field types

Records can contain a variety of field types. Earlier in this tutorial, you saw strings and booleans, but you can also specify a number of other types. Here is a complete list of all supported types:

  • String (NSString)
  • Boolean (NSNumber)
  • Integer (NSNumber) – 64 bits, signed
  • Floating point (NSNumber) – IEEE double
  • Date (NSDate) – POSIX-like timestamp stored with millisecond precision.
  • Bytes (NSData) – Arbitrary data, which is treated as binary, such as thumbnail images or compressed data. Individual records can be up to 100KB, which limits the size of the data. If you want to store larger files, you should use the Sync API and reference the paths to those files in your records.
  • List (DBList) – A special value that can contain other values, though not other lists.

Customizing conflict resolution

Datastores automatically merge changes on a per-field basis. If, for example, a user were to edit the taskname of a task on one device and the completed status of that same task on another device, the Datastore API would merge these changes without a conflict.

Sometimes, however, there will be simultaneous changes to the same field of the same record, and this requires conflict resolution. For example, if a user were to edit the completed status of a task on two different devices while offline, it's unclear how those changes should be merged when the devices come back online. Because of this ambiguity, app developers can choose what conflict resolution rule they want to follow.

To set the conflict resolution rule, call the -setResolutionRule:forField: method on a table, and pass in the name of a field and the resolution rule you want to apply to that field.

[taskTable setResolutionRule:DBResolutionLocal forField:@"completed"];

There are five available resolution rules that affect what happens when a remote change conflicts with a local change:

  • DBResolutionRemote – The remote value will be chosen. This is the default behavior for all fields.
  • DBResolutionLocal – The local value of the field will be chosen.
  • DBResolutionMax – The greater of the two changes will be chosen.
  • DBResolutionMin – The lesser of the two changes will be chosen.
  • DBResolutionSum – Additions and subtractions to the value will be preserved and combined.

Note that resolution rules don't persist, so you should set any custom resolution rules after opening a datastore but before the first time you sync.