Inherits from NSObject
Declared in DBDatastore.h

Overview

A datastore is a simple, syncable database for app data. You can open the default datastore using openDefaultStoreForAccount:error: and open or create other datastores using a DBDatastoreManager.

You interact with data in the datastore using tables. You can call getTable: to get a table, or getTables: to list all tables in a datastore containing records.

Changes you make to the datastore will be visible immediately, and calling sync: will persist outgoing changes and queue them to be uploaded to the server. While a datastore is open, it will monitor for remote changes and download them when possible. When there are remote changes waiting to be incorporated, the DBDatastoreStatus will have its incoming property set to YES, and calling sync: will also apply those changes to your view of the datastore, resolving any conflicts along the way.

To find out when there are changes ready to be synced, add an observer using addObserver:block: to register a block that will be called every time status changes.

Tasks

  • + isValidId:

    Returns YES if datastoreId is a valid ID for a DBDatastore, or NO otherwise. Datastore IDs come in 2 forms:

  • + openDefaultStoreForAccount:error:

    Opens the default datastore for this account.

  • + openDefaultLocalStoreForAccountManager:error:

    Opens the local default datastore for this account manager.

  • – close

    Close a datastore when you’re done using it to indicate that you are no longer interested in receiving updates for this datastore.

  • – getTables:

    Get all the tables in this datastore that contain records.

  • – getTable:

    Get a table with the specified ID, which can be used to insert or query records. If this is a new table ID, the table will not be visible until a record is inserted.

  •   title

    Set the title for this datastore. Will be nil if no title is set. Setting it to nil will delete the title field.

    property
  •   mtime

    The last modified time for this datastore, or nil if no data has been synced yet.

    property
  •   size

    The current size of this datastore in bytes. The overall size of a datastore is calculated by summing the size of all records, plus the base size of an empty datastore itself.

    property
  •   recordCount

    The total number of records in this datastore.

    property
  •   unsyncedChangesSize

    The size in bytes of changes that will be queued for upload by the next call to sync:.

    property
  • – sync:

    Apply all outstanding changes to the datastore, and also incorporate remote changes in.

  •   open

    Whether the datastore is currently open.

    property
  •   status

    The current sync status of the datastore.

    property
  • – addObserver:block:

    Add block as an observer when the status of the datastore changes.

  • – removeObserver:

    Remove all blocks registered for the given observer.

  •   datastoreId

    The ID for this datastore.

    property
  •   manager

    The datastore manager for this datastore.

    property

Properties

datastoreId

@property (nonatomic, readonly) NSString *datastoreId
Discussion

The ID for this datastore.

Declared In

DBDatastore.h

manager

@property (nonatomic, readonly) DBDatastoreManager *manager
Discussion

The datastore manager for this datastore.

Declared In

DBDatastore.h

mtime

@property (nonatomic, readonly) NSDate *mtime
Discussion

The last modified time for this datastore, or nil if no data has been synced yet.

The last modified time is automatically updated on each call to sync: which commits local changes, or incorporates remote changes. The timestamp is based on the local clock of the device where the change is made.

Declared In

DBDatastore.h

open

@property (nonatomic, readonly, getter=isOpen) BOOL open
Discussion

Whether the datastore is currently open.

Declared In

DBDatastore.h

recordCount

@property (nonatomic, readonly) NSUInteger recordCount
Discussion

The total number of records in this datastore.

Declared In

DBDatastore.h

size

@property (nonatomic, readonly) NSUInteger size
Discussion

The current size of this datastore in bytes. The overall size of a datastore is calculated by summing the size of all records, plus the base size of an empty datastore itself.

Declared In

DBDatastore.h

status

@property (nonatomic, readonly) DBDatastoreStatus *status
Discussion

The current sync status of the datastore.

Declared In

DBDatastore.h

title

@property (nonatomic, copy) NSString *title
Discussion

Set the title for this datastore. Will be nil if no title is set. Setting it to nil will delete the title field.

Declared In

DBDatastore.h

unsyncedChangesSize

@property (nonatomic, readonly) NSUInteger unsyncedChangesSize
Discussion

The size in bytes of changes that will be queued for upload by the next call to sync:.

Declared In

DBDatastore.h

Class Methods

isValidId:

+ (BOOL)isValidId:(NSString *)datastoreId
Discussion

Returns YES if datastoreId is a valid ID for a DBDatastore, or NO otherwise. Datastore IDs come in 2 forms:

Named datastores (such as the default datastore) use IDs which can be 1-64 characters long, must not begin or end with a ‘.’, and may contain lower-case letters, digits, and these punctuation characters: . - _ (Note that older SDKs limited these to 32 characters, so take care if your datastore needs to be accessed by legacy clients.)

Globally unique datastore IDs (generated by `[DBDatastoreManager createDatastore:]) always begin with a ‘.’ and can contain 1-63 additional characters which can be upper-case, lower-case, digits, and these punctuation characters: . -

Declared In

DBDatastore.h

openDefaultLocalStoreForAccountManager:error:

+ (DBDatastore *)openDefaultLocalStoreForAccountManager:(DBAccountManager *)accountManager error:(DBError **)error
Discussion

Opens the local default datastore for this account manager.

Local datastores and migration are a preview feature for testing only, and should not be used in production apps.

Declared In

DBDatastore.h

openDefaultStoreForAccount:error:

+ (DBDatastore *)openDefaultStoreForAccount:(DBAccount *)account error:(DBError **)error
Discussion

Opens the default datastore for this account.

Declared In

DBDatastore.h

Instance Methods

addObserver:block:

- (void)addObserver:(id)observer block:(DBObserver)block
Discussion

Add block as an observer when the status of the datastore changes.

Declared In

DBDatastore.h

close

- (void)close
Discussion

Close a datastore when you’re done using it to indicate that you are no longer interested in receiving updates for this datastore.

Any changes made since the last call to sync: will be discarded on close. If the account is unlinked remotely, the datastore will close automatically.

Declared In

DBDatastore.h

getTable:

- (DBTable *)getTable:(NSString *)tableId
Discussion

Get a table with the specified ID, which can be used to insert or query records. If this is a new table ID, the table will not be visible until a record is inserted.

Declared In

DBDatastore.h

getTables:

- (NSArray *)getTables:(DBError **)error
Discussion

Get all the tables in this datastore that contain records.

Declared In

DBDatastore.h

removeObserver:

- (void)removeObserver:(id)observer
Discussion

Remove all blocks registered for the given observer.

Declared In

DBDatastore.h

sync:

- (NSDictionary *)sync:(DBError **)error
Discussion

Apply all outstanding changes to the datastore, and also incorporate remote changes in.

Return Value

A dictionary mapping of tableId to a set of DBRecord objects if the call was successful, or nil if an error occurred. The table IDs and records in the dictionary correspond to the tables and records that changed due to remote changes applied during this sync. If records are deleted by the sync, the DBRecords will have the deleted property set, but no fields.

Declared In

DBDatastore.h