iOS
OS X
Android
JavaScript
Python
HTTP

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 for working with users within your app. The datastore manager allows your app to open datastores, get a list of datastores, wait for changes to multiple datastores, and so on. You can begin working with datastores right away using local datastores. Users can then link their Dropbox account at any time to sync their data.

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.

The unit of sharing is a single datastore, and one or more datastores may be shared between accounts. Any datastore with a shareable ID can be shared by assigning roles to principals, creating an access control list. Any Dropbox account with the correct permissions will then be able to open the shared datastore by ID.

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.

Initializing managers

To start using the Datastore API, you'll need to create a DBAccountManager object for working with a user's account. You'll also need to create a DBDatastoreManager for working with datastores in your app.

A good place to initialize both 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 {
    // Set up the account manager
    DBAccountManager *accountManager =
        [[DBAccountManager alloc] initWithAppKey:@"APP_KEY" secret:@"APP_SECRET"];
    [DBAccountManager setSharedManager:accountManager];

    // Set up the datastore manager
    DBAccount *account = [[DBAccountManager sharedManager] linkedAccount];
    if (account) {
        // Use Dropbox datastores
        [DBDatastoreManager setSharedManager:[DBDatastoreManager managerForAccount:account]];
    } else {
        // Use local datastores
        [DBDatastoreManager setSharedManager:[DBDatastoreManager localManagerForAccountManager:
                                                            [DBAccountManager sharedManager]]];
    }

    return YES;
}

Your app can use datastores without requiring users to login to Dropbox first. Note that we're checking if the user has linked their account yet and then either using Dropbox datatores or local datastores. Local datastores are stored on the local device, and not synced to Dropbox. You can later migrate these datastores to a Dropbox account when the user chooses to link.

Next let's add the ability to link the user's Dropbox account. This allows you to sync the user's data between devices.

Linking accounts

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. Keep in mind, you'll need all the pieces in this section in place before it will work end-to-end.

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 the request to complete the auth flow and migrate any local datastores.

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!");
        // Migrate any local datastores to the linked account
        DBDatastoreManager *localManager = [DBDatastoreManager localManagerForAccountManager:
                                                            [DBAccountManager sharedManager]];
        [localManager migrateToAccount:account error:nil];
        // Now use Dropbox datastores
        [DBDatastoreManager setSharedManager:[DBDatastoreManager managerForAccount:account]];
        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

For this tutorial, we'll use the default datastore. Each app has its own default datastore per user. You should retain the datastore for as long as you need it to sync.

Your view controller

@property (nonatomic, strong) DBDatastore *datastore;

You can use your datastoreManager to open the default datastore:

self.datastore = [[DBDatastoreManager sharedManager] openDefaultDatastore: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.datastore 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.datastore 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.datastore 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.datastore 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.datastore addObserver:self block:^() {
    if (weakSelf.datastore.status.incoming) {
        NSDictionary *changes = [weakSelf.datastore 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.datastore.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.

For some applications you may want to share data between users. The Datastore API allows you to share a datastore across multiple Dropbox accounts.

To share a datastore, you'll first need to update its permissions by assigning a role to a group of users (called a principal).

// Shareable datastore
DBDatastore *datastore = [[DBDatastoreManager sharedManager] createDatastore:nil];
[datastore setRoleForPrincipal:DBPrincipalPublic to:DBRoleEditor];
[datastore sync:nil];

Note that if your app is using local datastores, you can create a shareable datastore and update the permissions locally. However, the datastore can't actually be shared with others until after the user links their account to Dropbox and the data is migrated.

There are two available principals to whom you may apply a role:

DBPrincipalPublic – The role will apply to all Dropbox users.
DBPrincipalTeam – The role will apply to everyone on the user's team (only applicable for Dropbox for Business accounts).

There are four available roles:

DBRoleNone – The principal has no access to this datastore.
DBRoleViewer – The principal is able to view this datastore.
DBRoleEditor – The principal is able to edit this datastore.
DBRoleOwner – The principal is the owner of this datastore. This role cannot be assigned directly. The user who created a datastore is always that datastore's owner.

After assigning a role to a principal, you'll want to share the datastore ID with other users. A common way to share the datastore ID is to send a URL containing the datastore ID via email, text message, or some other mechanism within your app.

Any user who has the datastore ID and the appropriate permissions may then open the datastore:

if ([DBDatastore isValidShareableId:datastoreID]) {
    DBDatastore *datastore = [self.datastoreManager openDatastore:datastoreID error:nil];
}

At any time you may view the access control list for a datastore as a mapping of roles applied to principals using the listRoles method. You can also find out the current user's role with the effectiveRole method.

Example apps

See our example apps for more help getting started with the Datastore API.

Lists – A sample app that demonstrates many features of the Datastore API.
Click the Box – A simple app for storing game state using the Datastore API.

Contents

Choose a language

Using the Datastore API on iOS

Setting up the SDK

Initializing managers

YourAppDelegate.m

Linking accounts

Your view controller

YourAppDelegate.m

Creating a datastore and your first table

Your view controller

Working with records

Querying records

Using observers

Records and fields

Record IDs

Field types

Customizing conflict resolution

Sharing a datastore

Example apps

Choose a language