CBLDatabase

@interface CBLDatabase : NSObject

A Couchbase Lite database.

  • The database’s name.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull name;

  • The database’s path. If the database is closed or deleted, nil value will be returned.

    Declaration

    Objective-C

    @property (readonly, nullable) NSString *path;

  • The database’s configuration. The returned configuration object is readonly; an NSInternalInconsistencyException exception will be thrown if the configuration object is modified.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLDatabaseConfiguration *_Nonnull config;

Initializers

  • Initializes a database object with a given name and the default database configuration. If the database does not yet exist, it will be created.

    Declaration

    Objective-C

    - (nullable instancetype)initWithName:(nonnull NSString *)name
                                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The name of the database.
    error

    On return, the error if any.

  • Initializes a Couchbase Lite database with a given name and database configuration. If the database does not yet exist, it will be created.

    Declaration

    Objective-C

    - (nullable instancetype)initWithName:(nonnull NSString *)name
                               config:
                                   (nullable CBLDatabaseConfiguration *)config
                                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The name of the database.
    config

    The database configuration, or nil for the default configuration.
    error

    On return, the error if any.

  • Unavailable

    Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;

Blob Save/Get

  • Save a blob object directly into the database without associating it with any documents.

    Note: Blobs that are not associated with any documents will be removed from the database when compacting the database.

    Declaration

    Objective-C

    - (BOOL)saveBlob:(nonnull CBLBlob *)blob
           error:(NSError *_Nullable *_Nullable)error;

    Parameters

    blob

    The blob to save.
    error

    On return, the error if any.

    Return Value

    /True on success, false on failure.

  • Get a blob object using a blob’s metadata. If the blob of the specified metadata doesn’t exist, the nil value will be returned.

    @Note

    Key | Value | Mandatory | Description

    @type | constant string “blob” | Yes | Indicate Blob data type. content_type | String | No | Content type ex. text/plain. length | Number | No | Binary length of the Blob in bytes. digest | String | Yes | The cryptographic digest of the Blob’s content.

    Declaration

    Objective-C

    - (nullable CBLBlob *)getBlob:(nonnull NSDictionary *)properties;

    Parameters

    properties

    The properties for getting the blob object. If dictionary is not valid, it will throw InvalidArgument exception. See the note section

    Return Value

    Blob on success, otherwise nil.

Batch Operation

  • Runs a group of database operations in a batch. Use this when performing bulk write operations like multiple inserts/updates; it saves the overhead of multiple database commits, greatly improving performance.

    Declaration

    Objective-C

    - (BOOL)inBatch:(NSError *_Nullable *_Nullable)error
     usingBlock:(nonnull void (^)(void))block;

    Parameters

    error

    On return, the error if any.
    block

    The block to execute a group of database operations.

    Return Value

    True on success, false on failure.

Databaes Maintenance

  • Close database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

    Declaration

    Objective-C

    - (BOOL)close:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Close and delete the database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

    Declaration

    Objective-C

    - (BOOL)delete:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Performs database maintenance.

    Declaration

    Objective-C

    - (BOOL)performMaintenance:(CBLMaintenanceType)type
                     error:(NSError *_Nullable *_Nullable)error;

    Parameters

    type

    Maintenance type.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Deletes a database of the given name in the given directory.

    Declaration

    Objective-C

    + (BOOL)deleteDatabase:(nonnull NSString *)name
           inDirectory:(nullable NSString *)directory
                 error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

  • Checks whether a database of the given name exists in the given directory or not.

    Declaration

    Objective-C

    + (BOOL)databaseExists:(nonnull NSString *)name
           inDirectory:(nullable NSString *)directory;

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.

    Return Value

    True on success, false on failure.

  • Copies a canned databaes from the given path to a new database with the given name and the configuration. The new database will be created at the directory specified in the configuration. Without given the database configuration, the default configuration that is equivalent to setting all properties in the configuration to nil will be used.

    @Note This method will copy the database without changing the encryption key of the original database. The encryption key specified in the given config is the encryption key used for both the original and copied database. To change or add the encryption key for the copied database, call [Database changeEncryptionKey:error:] for the copy. @Note It is recommended to close the source database before calling this method.

    Declaration

    Objective-C

    + (BOOL)copyFromPath:(nonnull NSString *)path
          toDatabase:(nonnull NSString *)name
          withConfig:(nullable CBLDatabaseConfiguration *)config
               error:(NSError *_Nullable *_Nullable)error;

    Parameters

    path

    The source database path.
    name

    The name of the new database to be created.
    config

    The database configuration for the new database.
    error

    On return, the error if any.

    Return Value

    True on success, false on failure.

Scopes

  • Get scope names that have at least one collection.

    Note

    The default scope is exceptional as it will always be listed even though there are no collections under it.

    Declaration

    Objective-C

    - (nullable NSArray<CBLScope *> *)scopes:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    returns the scope names, or nil if an error occurred.

  • Get a scope object by name. As the scope cannot exist by itself without having a collection, the nil value will be returned if there are no collections under the given scope’s name.

    Note

    The default scope is exceptional, and it will always be returned.

    Declaration

    Objective-C

    - (nullable CBLScope *)scopeWithName:(nullable NSString *)name
                               error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    Scope name, if empty, it will use default scope name.
    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    Scope object, or nil if an error occurred.

Collections

  • Get all collections in the specified scope.

    Declaration

    Objective-C

    - (nullable NSArray<CBLCollection *> *)
    collections:(nullable NSString *)scope
          error:(NSError *_Nullable *_Nullable)error;

    Parameters

    scope

    Scope name
    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    list of collections in the scope, or nil if an error occurred.

  • Create a named collection in the specified scope.

    Declaration

    Objective-C

    - (nullable CBLCollection *)
    createCollectionWithName:(nonnull NSString *)name
                       scope:(nullable NSString *)scope
                       error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    name for the new collection
    scope

    collection will be created under this scope, if not specified, use the default scope.
    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    Newly created collection or if already exists, the existing collection will be returned , or nil if an error occurred.

  • Get a collection in the specified scope by name.

    Declaration

    Objective-C

    - (nullable CBLCollection *)collectionWithName:(nonnull NSString *)name
                                         scope:(nullable NSString *)scope
                                         error:(NSError *_Nullable *_Nullable)
                                                   error;

    Parameters

    name

    Name of the collection to be fetched.
    scope

    Name of the scope the collection resides, if not specified uses the default scope.
    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed. CBLErrorNotFound code will be returned if the collection doesn’t exist.

    Return Value

    collection instance or If the collection doesn’t exist, a nil value will be returned.

  • Delete a collection by name in the specified scope. If the collection doesn’t exist, the operation will be no-ops.

    Note

    The default collection cannot be deleted.

    Declaration

    Objective-C

    - (BOOL)deleteCollectionWithName:(nonnull NSString *)name
                           scope:(nullable NSString *)scope
                           error:(NSError *_Nullable *_Nullable)error;

    Parameters

    name

    Name of the collection to be deleted
    scope

    Name of the scope the collection resides, if not specified uses the default scope.
    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    True on success, false on failure.

  • Get the default scope.

    Declaration

    Objective-C

    - (nullable CBLScope *)defaultScope:(NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any. CBLErrorNotOpen code will be returned if the database is closed.

    Return Value

    Default Scope, or nil if an error occurred.

  • Get the default collection.

    Declaration

    Objective-C

    - (nullable CBLCollection *)defaultCollection:
    (NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    Default collection, or nil if an error occurred.

Encryption

  • ENTERPRISE EDITION ONLY.

    Changes the database’s encryption key, or removes encryption if the new key is nil.

    Declaration

    Objective-C

    - (BOOL)changeEncryptionKey:(nullable CBLEncryptionKey *)key
                      error:(NSError *_Nullable *_Nullable)error;

    Parameters

    key

    The encryption key.
    error

    On return, the error if any.

    Return Value

    True if the database was successfully re-keyed, or false on failure.

Prediction

  • ENTERPRISE EDITION ONLY

    The predictive model manager for registering and unregistering predictive models.

    Declaration

    Objective-C

    + (nonnull CBLPrediction *)prediction;