CBLDatabase
@interface CBLDatabase : NSObject
A Couchbase Lite database.
-
The database’s name.
Declaration
Objective-C
@property (readonly, nonatomic) NSString *_Nonnull name;
-
The database’s path. If the database is closed or deleted, nil value will be returned.
Declaration
Objective-C
@property (readonly, nonatomic, nullable) NSString *path;
-
The number of documents in the database.
Declaration
Objective-C
@property (readonly, nonatomic) uint64_t count;
-
The database’s configuration. If the configuration is not specify when initializing the database, the default configuration will be returned.
Declaration
Objective-C
@property (readonly, copy, nonatomic) 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. May NOT contain capital letters!
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. May NOT contain capital letters!
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 CBLDocument object with the given ID. If the 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 *)documentID;
Parameters
documentID
The document ID.
Return Value
The CBLDocument object.
-
Checks whether the document of the given ID exists in the database or not.
Declaration
Objective-C
- (BOOL)contains:(nonnull NSString *)documentID;
Parameters
documentID
The document ID.
Return Value
True if the database contains the document with the given ID, otherwise false.
-
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 the given document to the database. If the document in the database has been updated since it was read by this CBLDocument, a conflict occurs, which will be resolved by invoking the conflict handler. This can happen if multiple application threads are writing to the database, or a pull replication is copying changes from a server.
Declaration
Objective-C
- (BOOL)saveDocument:(nonnull CBLDocument *)document error:(NSError *_Nullable *_Nullable)error;
Parameters
document
The document to be saved.
error
On return, the error if any.
Return Value
True on success, false on failure.
-
Deletes the given document. All properties are removed, and subsequent calls to -documentWithID: will return nil. Deletion adds a special
tombstone
revision to the database, as bookkeeping so that the change can be replicated to other databases. Thus, it does not free up all of the disk space occupied by the document. To delete a document entirely (but without the ability to replicate this), use -purge:error:.Declaration
Objective-C
- (BOOL)deleteDocument:(nonnull CBLDocument *)document error:(NSError *_Nullable *_Nullable)error;
Parameters
document
The document to be deleted.
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.
-
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 do:(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.
-
Closes a database.
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.
-
Deletes a database.
Declaration
Objective-C
- (BOOL)deleteDatabase:(NSError *_Nullable *_Nullable)error;
Parameters
error
On return, the error if any.
Return Value
True on success, false on failure.
-
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.
-
Changes the database’s encryption key, or removes encryption if the new key is nil.
Declaration
Objective-C
- (BOOL)setEncryptionKey:(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.
-
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 config:(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.
-
Sets log level for the given log domain.
Declaration
Objective-C
+ (void)setLogLevel:(CBLLogLevel)level domain:(CBLLogDomain)domain;
Parameters
level
The log level.
domain
The log domain.
-
Adds a database change listener block.
Declaration
Objective-C
- (nonnull id<NSObject>)addChangeListener: (nonnull void (^)(CBLDatabaseChange *_Nonnull))block;
Parameters
block
The block to be executed when the change is received.
Return Value
An opaque object to act as the listener and for removing the listener when calling the -removeChangeListener: method.
-
Adds a document change listener block for the given document ID.
Declaration
Objective-C
- (nonnull id<NSObject>) addChangeListenerForDocumentID:(nonnull NSString *)documentID usingBlock: (nonnull void (^)(CBLDocumentChange *_Nonnull))block;
Parameters
documentID
The document.
block
The block to be executed when the change is received.
Return Value
An opaque object to act as the listener and for removing the listener when calling the -removeChangeListener: method.
-
Removes a change listener. The given change listener is the opaque object returned by the -addChangeListener: or -addChangeListenerForDocumentID:usingBlock: method.
Declaration
Objective-C
- (void)removeChangeListener:(nonnull id<NSObject>)listener;
Parameters
listener
The listener object to be removed.
-
All index names.
Declaration
Objective-C
@property (readonly, atomic) 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.
-
Enumerates all documents in the database, ordered by document ID.
Declaration
Objective-C
- (nonnull NSEnumerator<CBLDocument *> *)allDocuments;
Return Value
All documents.
-
Compiles a database query, from any of several input formats. Once compiled, the query can be run many times with different parameter values. The rows will be sorted by ascending document ID, and no custom values are returned.
Declaration
Objective-C
- (nonnull CBLPredicateQuery *)createQueryWhere:(nullable id)where;
Parameters
where
The query specification. This can be an NSPredicate, or an NSString (interpreted as an NSPredicate format string), or nil to return all documents.
Return Value
The CBLQuery.