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 (atomic, readonly, nullable) NSString *path;
-
The number of documents in the database.
Declaration
Objective-C
@property (atomic, readonly) uint64_t count;
-
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;
-
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.
-
Not available
Declaration
Objective-C
- (nonnull instancetype)init;
-
Gets an existing document with the given ID. If a document with the given ID doesn’t exist in the database, the value returned will be nil.
Declaration
Objective-C
- (nullable CBLDocument *)documentWithID:(nonnull NSString *)id;
Parameters
id
The document ID.
Return Value
The CBLDocument object.
-
Gets a document fragment with the given document ID.
Declaration
Objective-C
- (nonnull CBLDocumentFragment *)objectForKeyedSubscript: (nonnull NSString *)documentID;
Parameters
documentID
The document ID.
Return Value
The CBLDocumentFragment object.
-
Saves a document to the database. 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.
-
Saves a document to the database. 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.
-
Saves a document to the database. 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.
-
Deletes a document from the database. 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.
-
Deletes a document from the database. 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.
-
Purges the given document from the database. 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.
-
Purges the document for the given documentID from the database. 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.
-
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.
-
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.
-
This method is deprecated. Compacts the database file by deleting unused attachment files and vacuuming the SQLite database
Declaration
Objective-C
- (BOOL)compact:(NSError *_Nullable *_Nullable)error;
Parameters
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.
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.
-
This function is deprecated. Use CBLDatabase.log.console to set log level and domains instead.
Declaration
Objective-C
+ (void)setLogLevel:(CBLLogLevel)level domain:(CBLLogDomain)domain;
Parameters
level
The log level.
domain
The log domain.
-
Log object used for configuring console, file, and custom logger.
Declaration
Objective-C
+ (nonnull CBLLog *)log;
Return Value
log object
-
Adds a database change listener. 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.
-
Adds a database change listener 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.
-
Adds a document change listener for the document with the given ID. 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.
-
Adds a document change listener for the document with the given ID and 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.
-
Removes a change listener with the given listener token.
Declaration
Objective-C
- (void)removeChangeListenerWithToken:(nonnull id<CBLListenerToken>)token;
Parameters
token
The listener token.
-
All index names.
Declaration
Objective-C
@property (atomic, readonly) NSArray<NSString *> *_Nonnull indexes;
-
Creates an index which could be a value index or a full-text search index with the given name. The name can be used 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
error On return, the error if any.
Return Value
True on success, false on failure.
-
Deletes the index of the given index name.
Declaration
Objective-C
- (BOOL)deleteIndexForName:(nonnull NSString *)name error:(NSError *_Nullable *_Nullable)error;
Parameters
name
The index name.
error
error On return, the error if any.
Return Value
True on success, false on failure.
-
Sets an expiration date on a document. 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
error On return, the error if any.
Return Value
True on success, false on failure.
-
Returns the expiration time of a document, 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.
-
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.
-
ENTERPRISE EDITION ONLY
The predictive model manager for registering and unregistering predictive models.
Declaration
Objective-C
+ (nonnull CBLPrediction *)prediction;