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;

INITIALIZER

  • Initializes a database object with a given name and the default database configuration. If the database does not yet exist, it will be created. - parameter: name The name of the database. May NOT contain capital letters! - parameter: error On return, the error if any.

    Declaration

    Objective-C

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

    Parameters

    name
    error

  • Initializes a Couchbase Lite database with a given name and database configuration. If the database does not yet exist, it will be created, unless the readOnly option is used. - parameter: name The name of the database. May NOT contain capital letters! - parameter: config The database configuration, or nil for the default configuration. - parameter: error On return, the error if any.

    Declaration

    Objective-C

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

    Parameters

    name
    config
    error

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;

GET EXISTING DOCUMENT

  • 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. - parameter: documentID the document ID. @result the CBLDocument object.

    Declaration

    Objective-C

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

    Parameters

    documentID

CHECK DOCUMENT EXISTS

  • Checks whether the document of the given ID exists in the database or not.

    Declaration

    Objective-C

    - (BOOL)contains:(nonnull NSString *)documentID;

SUBSCRIPTION

SAVE DELETE PURGE

  • 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;

  • 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;

  • 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;

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
             do:(nonnull void (^)(void))block;

DATABASE MAINTENANCE

  • Closes a database.

    Declaration

    Objective-C

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

  • Deletes a database.

    Declaration

    Objective-C

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

  • Compacts the database file by deleting unused attachment files and vacuuming the SQLite database

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

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

    Parameters

    key

    The encryption key in the form of an NSString (a password) or an NSData object exactly 32 bytes in length (a raw AES key.) If a string is given, it will be internally converted to a raw key using 64,000 rounds of PBKDF2 hashing. A nil value will decrypt the database.
    error

    If an error occurs, it will be stored here if this parameter is non-NULL. @result YES if the database was successfully re-keyed, or NO on 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;

  • 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;

DOCUMENT CHANGES

  • Add a document change listener to the document. - parameter: listener the listener. - parameter: documentID the document ID.

    Declaration

    Objective-C

    - (void)addChangeListener:(nonnull id<CBLDocumentChangeListener>)listener
            forDocumentID:(nonnull NSString *)documentID;

    Parameters

    listener
    documentID

  • Remove the document change listener from the document. - parameter: listener the listener. - parameter: documentID the document ID.

    Declaration

    Objective-C

    - (void)removeChangeListener:(nonnull id<CBLDocumentChangeListener>)listener
               forDocumentID:(nonnull NSString *)documentID;

    Parameters

    listener
    documentID

QUERYING:

  • Enumerates all documents in the database, ordered by document ID.

    Declaration

    Objective-C

    - (nonnull NSEnumerator<CBLDocument *> *)allDocuments;

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

  • Creates a value index (type kCBLValueIndex) on a given document property. This will speed up queries that test that property, at the expense of making database writes a little bit slower. - parameter: expressions Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings. - parameter: error If an error occurs, it will be stored here if this parameter is non-NULL. - returns: True on success, false on failure.

    Declaration

    Objective-C

    - (BOOL)createIndexOn:(nonnull NSArray *)expressions
                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    expressions
    error

  • Creates an index on a given document property. This will speed up queries that test that property, at the expense of making database writes a little bit slower. - parameter: expressions Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings. - parameter: type Type of index to create (value, full-text or geospatial.) - parameter: options Options affecting the index, or NULL for default settings. - parameter: error If an error occurs, it will be stored here if this parameter is non-NULL. - returns: True on success, false on failure.

    Declaration

    Objective-C

    - (BOOL)createIndexOn:(nonnull NSArray *)expressions
                 type:(CBLIndexType)type
              options:(nullable const CBLIndexOptions *)options
                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    expressions
    type
    options
    error

  • Deletes an existing index. Returns NO if the index did not exist. - parameter: expressions Expressions indexed (same parameter given to -createIndexOn:.) - parameter: type Type of index. - parameter: error If an error occurs, it will be stored here if this parameter is non-NULL. - returns: True if the index existed and was deleted, false if it did not exist.

    Declaration

    Objective-C

    - (BOOL)deleteIndexOn:(nonnull NSArray *)expressions
                 type:(CBLIndexType)type
                error:(NSError *_Nullable *_Nullable)error;

    Parameters

    expressions
    type
    error