CBLDatabase

@interface CBLDatabase : NSObject

A Couchbase Lite database.

  • The database’s name.

    Declaration

    Objective-C

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

    Swift

    var name: String { get }

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

    Swift

    var path: String? { get }

  • Initializes a database object with a given name and the default database options. 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;

    Swift

    convenience init(name: String) throws

    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 options. 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: options The database options, or nil for the default options. - parameter: error On return, the error if any.

    Declaration

    Objective-C

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

    Swift

    init(name: String, options: CBLDatabaseOptions?) throws

    Parameters

    name

    The name of the database. May NOT contain capital letters!
    options

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

    On return, the error if any.

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Closes a database.

    Declaration

    Objective-C

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

    Swift

    func close() throws

  • Changes the database’s encryption key, or removes encryption if the new key is nil. - parameter: 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. - parameter: 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.

    Declaration

    Objective-C

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

    Swift

    func changeEncryptionKey(_ key: Any?) throws

    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.

  • Deletes a database.

    Declaration

    Objective-C

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

    Swift

    func delete() throws

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

    Swift

    class func delete(_ name: String, inDirectory directory: String?) throws

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

    Swift

    class func databaseExists(_ name: String, inDirectory directory: String?) -> Bool

  • 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 (^)())block;

    Swift

    func inBatch(do block: () -> Void) throws

  • Creates a new CBLDocument object with no properties and a new (random) UUID. The document will be saved to the database when you call -save: on it.

    Declaration

    Objective-C

    - (nonnull CBLDocument *)document;

    Swift

    func document() -> CBLDocument

  • Gets or creates a CBLDocument object with the given ID. The existence of the CBLDocument in the database can be checked by checking its .exists. CBLDocuments are cached, so there will never be more than one instance in this CBLDatabase object at a time with the same documentID.

    Declaration

    Objective-C

    - (nonnull CBLDocument *)documentWithID:(nonnull NSString *)docID;

    Swift

    func document(withID docID: String) -> CBLDocument

  • Same as -documentWithID:

    Declaration

    Objective-C

    - (nonnull CBLDocument *)objectForKeyedSubscript:(nonnull NSString *)docID;

    Swift

    subscript(docID: String) -> CBLDocument { get }

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

    Declaration

    Objective-C

    - (BOOL)documentExists:(nonnull NSString *)docID;

    Swift

    func documentExists(_ docID: String) -> Bool

  • The conflict resolver for this database. If nil, a default algorithm will be used, where the revision with more history wins. An individual document can override this for itself by setting its own property.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic, nullable) id<CBLConflictResolver>
    conflictResolver;

QUERYING:

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

    Declaration

    Objective-C

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

    Swift

    func allDocuments() -> NSEnumerator

  • 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. - parameter: where The query specification. This can be an NSPredicate, or an NSString (interpreted as an NSPredicate format string), or nil to return all documents. - returns: The CBLQuery.

    Declaration

    Objective-C

    - (nonnull CBLPredicateQuery *)createQueryWhere:(nullable id)where;

    Swift

    func createQueryWhere(_ where: Any?) -> CBLPredicateQuery

    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;

    Swift

    func createIndex(on expressions: [Any]) throws

    Parameters

    expressions

    Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings.
    error

    If an error occurs, it will be stored here if this parameter is non-NULL.

    Return Value

    True on success, false on failure.

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

    Swift

    func createIndex(on expressions: [Any], type: CBLIndexType, options: UnsafePointer

    Parameters

    expressions

    Expressions to index, typically key-paths. Can be NSExpression objects, or NSStrings that are expression format strings.
    type

    Type of index to create (value, full-text or geospatial.)
    options

    Options affecting the index, or NULL for default settings.
    error

    If an error occurs, it will be stored here if this parameter is non-NULL.

    Return Value

    True on success, false on failure.

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

    Swift

    func deleteIndex(on expressions: [Any], type: CBLIndexType) throws

    Parameters

    expressions

    Expressions indexed (same parameter given to -createIndexOn:.)
    type

    Type of index.
    error

    If an error occurs, it will be stored here if this parameter is non-NULL.

    Return Value

    True if the index existed and was deleted, false if it did not exist.