CBLDatabase Class Reference


                    
                    
                    name

The database’s name.

Declaration

Objective-C

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

path
The database’s path. If the database is closed or deleted, nil value will be returned.
Declaration
Objective-C

@property (readonly, nullable) NSString *path;
count
Deprecated

Use [database defaultCollection].count instead.

The number of documents in the database.
Declaration
Objective-C

@property (readonly) uint64_t count;
config
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


                    
                    
                    -initWithName:error:

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.


                    
                    
                    -initWithName:config:error:

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.

-init
Unavailable

Not available
Declaration
Objective-C

- (nonnull instancetype)init;

Get Existing Document


                    
                    
                    -documentWithID:

Deprecated

Use [database defaultCollection] documentWithID:] instead.

Gets an existing document from the default collection by document ID. If the document doesn’t exist in the database, nil will be returned.

Declaration

Objective-C

- (nullable CBLDocument *)documentWithID:(nonnull NSString *)id;

Parameters

`id`	The document ID.

Return Value

The CBLDocument object.

Subscript


                    
                    
                    -objectForKeyedSubscript:

Deprecated

Use [[database defaultCollection] objectForKeyedSubscript:] instead.

Gets a document fragment from the default collection by document ID.

Declaration

Objective-C

- (nonnull CBLDocumentFragment *)objectForKeyedSubscript:
    (nonnull NSString *)documentID;

Parameters


                                documentID

The document ID.

Return Value

The CBLDocumentFragment object.

Save, Delete, Purge


                    
                    
                    -saveDocument:error:

Deprecated

Use [[database defaultCollection] saveDocument:error:] instead.

Saves a document to the default collection. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling the -saveDocument:concurrencyControl:error: method with kCBLConcurrencyControlLastWriteWins concurrency control.

Declaration

Objective-C

- (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
               error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -saveDocument:concurrencyControl:error:

Deprecated

Use [[database defaultCollection] saveDocument:concurrencyControl:error:] instead.

Saves a document to the default collection. When used with kCBLConcurrencyControlLastWriteWins concurrency control, the last write operation will win if there is a conflict. When used with kCBLConcurrencyControlFailOnConflict concurrency control, save will fail with ‘CBLErrorConflict’ error code returned.

Declaration

Objective-C

- (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
    concurrencyControl:(CBLConcurrencyControl)concurrencyControl
                 error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document.
`concurrencyControl`	The concurrency control.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -saveDocument:conflictHandler:error:

Deprecated

Use [[database defaultCollection] saveDocument:conflictHandler:error:] instead.

Saves a document to the default collection. When write operations are executed concurrently and if conflicts occur, the conflict handler will be called. Use the conflict handler to directly edit the document to resolve the conflict. When the conflict handler returns ‘true’, the save method will save the edited document as the resolved document. If the conflict handler returns ‘false’, the save operation will be canceled with ‘false’ value returned as the conflict wasn’t resolved.

Declaration

Objective-C

- (BOOL)saveDocument:(nonnull CBLMutableDocument *)document
     conflictHandler:(nonnull BOOL (^)(CBLMutableDocument *_Nonnull,
                                       CBLDocument *_Nonnull))conflictHandler
               error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document.
`conflictHandler`	The conflict handler block which can be used to resolve it.
`error`	On return, error if any.

Return Value

True if successful. False if there is a conflict, but the conflict wasn’t resolved as the conflict handler returns ‘false’ value.


                    
                    
                    -deleteDocument:error:

Deprecated

Use [[database defaultCollection] deleteDocument:error:] instead.

Deletes a document from the default collection. When write operations are executed concurrently, the last writer will overwrite all other written values. Calling this method is the same as calling the -deleteDocument:concurrencyControl:error: method with kCBLConcurrencyControlLastWriteWins concurrency control.

Declaration

Objective-C

- (BOOL)deleteDocument:(nonnull CBLDocument *)document
                 error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document.
`error`	On return, the error if any.

Return Value

/True on success, false on failure.


                    
                    
                    -deleteDocument:concurrencyControl:error:

Deprecated

Use [[database defaultCollection] deleteDocument:concurrencyControl:error:] instead.

Deletes a document from the default collection. When used with kCBLConcurrencyControlLastWriteWins concurrency control, the last write operation will win if there is a conflict. When used with kCBLConcurrencyControlFailOnConflict concurrency control, delete will fail with ‘CBLErrorConflict’ error code returned.

Declaration

Objective-C

- (BOOL)deleteDocument:(nonnull CBLDocument *)document
    concurrencyControl:(CBLConcurrencyControl)concurrencyControl
                 error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document.
`concurrencyControl`	The concurrency control.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -purgeDocument:error:

Deprecated

Use [[database defaultCollection] purgeDocument:error:] instead.

Purges the given document from the default collection. This is more drastic than deletion: it removes all traces of the document. The purge will NOT be replicated to other databases.

Declaration

Objective-C

- (BOOL)purgeDocument:(nonnull CBLDocument *)document
                error:(NSError *_Nullable *_Nullable)error;

Parameters

`document`	The document to be purged.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -purgeDocumentWithID:error:

Deprecated

Use [[database defaultCollection] purgeDocumentWithID:error:] instead.

Purges the document with the given document ID from the default collection This is more drastic than deletion: it removes all traces of the document. The purge will NOT be replicated to other databases.

Declaration

Objective-C

- (BOOL)purgeDocumentWithID:(nonnull NSString *)documentID
                      error:(NSError *_Nullable *_Nullable)error;

Parameters

`documentID`	The ID of the document to be purged.
`error`	On return, the error if any.

Return Value

True on success, false on failure.

Blob Save/Get


                    
                    
                    -saveBlob:error:

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.


                    
                    
                    -getBlob:

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

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


                    
                    
                    -inBatch:usingBlock:

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:

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.


                    
                    
                    -delete:

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.


                    
                    
                    -performMaintenance:error:

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.


                    
                    
                    +deleteDatabase:inDirectory:error:

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.


                    
                    
                    +databaseExists:inDirectory:

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.


                    
                    
                    +copyFromPath:toDatabase:withConfig:error:

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.

Logging

+log
Log object used for configuring console, file, and custom logger.
Declaration
Objective-C

+ (nonnull CBLLog *)log;
Return Value

log object

Change Listener


                    
                    
                    -addChangeListener:

Deprecated

Use [[database defaultCollection] addChangeListener:] instead.

Adds a change listener to listen to changes in the default collection. Changes will be posted on the main queue.

Declaration

Objective-C

- (nonnull id<CBLListenerToken>)addChangeListener:
    (nonnull void (^)(CBLDatabaseChange *_Nonnull))listener;

Parameters


                                listener

The listener to post the changes.

Return Value

An opaque listener token object for removing the listener.


                    
                    
                    -addChangeListenerWithQueue:listener:

Deprecated

Use [[database defaultCollection] addChangeListenerWithQueue:listener:] instead.

Adds a change listener to listen to changes in the default collection with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

Declaration

Objective-C

- (nonnull id<CBLListenerToken>)
    addChangeListenerWithQueue:(nullable dispatch_queue_t)queue
                      listener:(nonnull void (^)(CBLDatabaseChange *_Nonnull))
                                   listener;

Parameters

`queue`	The dispatch queue.
`listener`	The listener to post changes.

Return Value

An opaque listener token object for removing the listener.


                    
                    
                    -addDocumentChangeListenerWithID:listener:

Deprecated

Use [[database defaultCollection] addDocumentChangeListenerWithID:listener:] instead.

Adds a document change listener for the document with the given document ID in the default collection. Changes will be posted on the main queue.

Declaration

Objective-C

- (nonnull id<CBLListenerToken>)
    addDocumentChangeListenerWithID:(nonnull NSString *)id
                           listener:(nonnull void (^)(
                                        CBLDocumentChange *_Nonnull))listener;

Parameters

`id`	The document ID.
`listener`	The listener to post changes.

Return Value

An opaque listener token object for removing the listener.


                    
                    
                    -addDocumentChangeListenerWithID:queue:listener:

Deprecated

Use [[database defaultCollection] addDocumentChangeListenerWithID:queue:listener:] instead.

Adds a document change listener for the document of the given document ID in the default collection with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

Declaration

Objective-C

- (nonnull id<CBLListenerToken>)
    addDocumentChangeListenerWithID:(nonnull NSString *)id
                              queue:(nullable dispatch_queue_t)queue
                           listener:(nonnull void (^)(
                                        CBLDocumentChange *_Nonnull))listener;

Parameters

`id`	The document ID.
`queue`	The dispatch queue.
`listener`	The listener to post changes.

Return Value

An opaque listener token object for removing the listener.


                    
                    
                    -removeChangeListenerWithToken:

Deprecated

Use [ListenerToken remove] instead.

Removes a change listener with the given listener token.

Declaration

Objective-C

- (void)removeChangeListenerWithToken:(nonnull id<CBLListenerToken>)token;

Parameters


                                token

The listener token.

Index


                    
                    
                    indexes

Deprecated

Use [[database defaultCollection] indexes] instead.

All index names.

Declaration

Objective-C

@property (readonly) __deprecated_msg("Use [[database defaultCollection] indexes] instead.") NSArray<NSString *> *indexes;


                    
                    
                    -createIndex:withName:error:

Deprecated

Use [[database defaultCollection] createIndexWithConfig:name:error:] instead.

Creates an index with the index name in the default collection. The index could be a value index or a full-text index. The index name can be used later for deleting the index. Creating a new different index with an existing index name will replace the old index. Creating the same index with the same name will be no-ops.

Declaration

Objective-C

- (BOOL)createIndex:(nonnull CBLIndex *)index
           withName:(nonnull NSString *)name
              error:(NSError *_Nullable *_Nullable)error;

Parameters

`index`	The index.
`name`	The index name.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -createIndexWithConfig:name:error:

Deprecated

Use [[database defaultCollection] createIndexWithConfig:name:error:] instead.

Creates an index in the default collection with the index config and the index name. The index config could be a value index or a full-text index. The index name can be used later for deleting the index. Creating a new different index with an existing index name will replace the old index. Creating the same index with the same name will be no-ops.

Declaration

Objective-C

- (BOOL)createIndexWithConfig:(nonnull CBLIndexConfiguration *)config
                         name:(nonnull NSString *)name
                        error:(NSError *_Nullable *_Nullable)error;

Parameters

`config`	The index configuration
`name`	The index name.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -deleteIndexForName:error:

Deprecated

Use [[database defaultCollection] deleteIndexForName:error:] instead.

Deletes the index from the default collection by name.

Declaration

Objective-C

- (BOOL)deleteIndexForName:(nonnull NSString *)name
                     error:(NSError *_Nullable *_Nullable)error;

Parameters

`name`	The index name.
`error`	On return, the error if any.

Return Value

True on success, false on failure.

DOCUMENT EXPIRATION


                    
                    
                    -setDocumentExpirationWithID:expiration:error:

Deprecated

Use [[database defaultCollection] setDocumentExpirationWithID:expiration:error:] instead.

Sets an expiration date on a document in the default collection. After this time the document will be purged from the database.

Declaration

Objective-C

- (BOOL)setDocumentExpirationWithID:(nonnull NSString *)documentID
                         expiration:(nullable NSDate *)date
                              error:(NSError *_Nullable *_Nullable)error;

Parameters

`documentID`	The ID of the document to set the expiration date for
`date`	The expiration date. Set nil date will reset the document expiration.
`error`	On return, the error if any.

Return Value

True on success, false on failure.


                    
                    
                    -getDocumentExpirationWithID:

Deprecated

Use [[database defaultCollection] getDocumentExpirationWithID:] instead.

Returns the expiration time of a document in the default collection, if exists, else nil.

Declaration

Objective-C

- (nullable NSDate *)getDocumentExpirationWithID:(nonnull NSString *)documentID;

Parameters


                                documentID

The ID of the document to set the expiration date for

Return Value

the expiration time of a document, if one has been set, else nil.

Scopes


                    
                    
                    -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.


                    
                    
                    -scopeWithName:error:

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


                    
                    
                    -collections:error:

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.


                    
                    
                    -createCollectionWithName:scope:error:

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.


                    
                    
                    -collectionWithName:scope:error:

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.


                    
                    
                    -deleteCollectionWithName:scope:error:

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.


                    
                    
                    -defaultScope:

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.


                    
                    
                    -defaultCollection:

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


                    
                    
                    -changeEncryptionKey:error:

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

+prediction
ENTERPRISE EDITION ONLY

The predictive model manager for registering and unregistering predictive models.
Declaration
Objective-C

+ (nonnull CBLPrediction *)prediction;