Database

public final class Database

A Couchbase Lite database.

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

    Throws

    An error when the database cannot be opened.

    Declaration

    Swift

    public init(name: String, config: DatabaseConfiguration = DatabaseConfiguration()) throws

    Parameters

    name

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

    The database options, or nil for the default options.

  • The database’s name.

    Declaration

    Swift

    public var name: String

  • The database’s path. If the database is closed or deleted, nil value will be returned.

    Declaration

    Swift

    public var path: String?

  • The total numbers of documents in the database.

    Declaration

    Swift

    public var count: UInt64

  • The database configuration.

    Declaration

    Swift

    public var config: DatabaseConfiguration

  • Gets a Document object with the given ID.

    Declaration

    Swift

    public func getDocument(_ id: String) -> Document?

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

    Declaration

    Swift

    public func contains(_ docID: String) -> Bool

  • Gets document fragment object by the given document ID.

    Declaration

    Swift

    public subscript(id: String) -> DocumentFragment

  • Throws

    An error on a failure.

    Declaration

    Swift

    public func save(_ document: Document) throws

    Parameters

    document

    The document.

  • Deletes the given document. All properties are removed, and subsequent calls to the getDocument(id) method 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.

    Throws

    An error on a failure.

    Declaration

    Swift

    public func delete(_ document: Document) throws

    Parameters

    document

    The document.

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

    Throws

    An error on a failure.

    Declaration

    Swift

    public func purge(_ document: Document) throws

    Parameters

    document

    The document.

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

    Throws

    An error on a failure.

    Declaration

    Swift

    public func inBatch(_ block: () throws -> Void ) throws

    Parameters

    block

    The block to be executed as a batch operations.

  • Adds a database change listener block.

    Declaration

    Swift

    @discardableResult public func addChangeListener(_ block: @escaping (DatabaseChange) -> Void)
        -> NSObjectProtocol

    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

    Swift

    public func addChangeListener(documentID: String,
                                  using block: @escaping (DocumentChange) -> Void) -> NSObjectProtocol

    Parameters

    documentID

    The document ID.
    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() method.

    Declaration

    Swift

    public func removeChangeListener(_ listener: NSObjectProtocol)

    Parameters

    listener

    The listener object to be removed.

  • Closes a database.

    Throws

    An error on a failure.

    Declaration

    Swift

    public func close() throws

  • Deletes a database.

    Throws

    An error on a failure.

    Declaration

    Swift

    public func delete() throws

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

    Throws

    An error on a failure

    Declaration

    Swift

    public func compact() throws

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

    Throws

    An error on a failure.

    Declaration

    Swift

    public func setEncryptionKey(_ key: EncryptionKey?) throws

    Parameters

    key

    The encryption key.

  • Deletes a database of the given name in the given directory.

    Throws

    An error on a failure.

    Declaration

    Swift

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

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.

  • Checks whether a database of the given name exists in the given directory or not.

    Declaration

    Swift

    public class func exists(_ name: String, inDirectory directory: String? = nil) -> Bool

    Parameters

    name

    The database name.
    directory

    The directory where the database is located at.

    Return Value

    True if the database exists, otherwise false.

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

    Throws

    An error on a failure.

    Declaration

    Swift

    public class func copy(fromPath path: String, toDatabase name: String,
                           config: DatabaseConfiguration?) throws

    Parameters

    path

    The source database path.
    name

    The name of the new database to be created.
    config

    The database configuration for the new database name.

  • Set log level for the given log domain.

    Declaration

    Swift

    public class func setLogLevel(_ level: LogLevel, domain: LogDomain)

    Parameters

    level

    The log level.
    domain

    The log domain.

  • All index names.

    Declaration

    Swift

    public var indexes: Array<String>

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

    Throws

    An error on a failure.

    Declaration

    Swift

    public func createIndex(_ index: Index, withName name: String) throws

    Parameters

    index

    The index.
    name

    The index name.

  • Deletes the index of the given index name.

    Throws

    An error on a failure.

    Declaration

    Swift

    public func deleteIndex(forName name: String) throws

    Parameters

    name

    The index name.

  • An iterator over all documents in the database, ordered by document ID.

    Declaration

    Swift

    public var allDocuments: DocumentIterator

  • Compiles a database query, from any of several input formats. Once compiled, the query can be run many times with different parameter values.

    Declaration

    Swift

    public func createQuery(where wherePredicate: Predicate? = nil,
                            groupBy: [PredicateExpression]? = nil,
                            having: Predicate? = nil,
                            returning: [PredicateExpression]? = nil,
                            distinct: Bool = false,
                            orderBy: [SortDescriptor]? = nil) -> PredicateQuery

    Parameters

    wherePredicate

    The where predicate.
    groupBy

    The group by expressions.
    having

    The having predicate.
    returning

    The returning values.
    distinct

    The distict flag.
    orderBy

    The order by as an array of the SortDescriptor object.

    Return Value

    The Predicate Query.