Show / Hide Table of Contents

Class Database

A Couchbase Lite database. This class is responsible for CRUD operations revolving around Document instances. It is portable between platforms if the file is retrieved, and can be seeded with pre-populated data if desired.

Inheritance
System.Object
Database
Implements
System.IDisposable
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Couchbase.Lite
Assembly: Couchbase.Lite.dll
Syntax
public sealed class Database : IDisposable

Constructors

| Improve this Doc View Source

Database(String, DatabaseConfiguration)

Creates a database with a given name and database configuration. If the configuration is null then the default configuration will be used. If the database does not yet exist, it will be created.

Declaration
public Database(string name, DatabaseConfiguration configuration = null)
Parameters
Type Name Description
System.String name

The name of the database

DatabaseConfiguration configuration

The database configuration, or null for the default configuration

Exceptions
Type Condition
System.ArgumentNullException

Thrown if name is null

CouchbaseLiteException

Thrown with CantOpenFile if the directory indicated in configuration could not be created

CouchbaseException

Thrown if an error condition was returned by LiteCore

Properties

| Improve this Doc View Source

Config

Gets the configuration that was used to create the database. The returned object is readonly; an System.InvalidOperationException will be thrown if the configuration object is modified.

Declaration
public DatabaseConfiguration Config { get; }
Property Value
Type Description
DatabaseConfiguration
| Improve this Doc View Source

Count

Gets the number of documents in the database

Declaration
public ulong Count { get; }
Property Value
Type Description
System.UInt64
| Improve this Doc View Source

Item[String]

Gets a DocumentFragment with the given document ID

Declaration
public DocumentFragment this[string id] { get; }
Parameters
Type Name Description
System.String id

The ID of the DocumentFragment to retrieve

Property Value
Type Description
DocumentFragment

The DocumentFragment object

| Improve this Doc View Source

Log

Gets the object that stores the available logging methods for Couchbase Lite

Declaration
public static Log Log { get; }
Property Value
Type Description
Log
| Improve this Doc View Source

Name

Gets the database's name

Declaration
public string Name { get; }
Property Value
Type Description
System.String
| Improve this Doc View Source

Path

Gets the database's path. If the database is closed or deleted, a null value will be returned.

Declaration
public string Path { get; }
Property Value
Type Description
System.String
| Improve this Doc View Source

Prediction

Gets the prediction manager that stores predictive models

Declaration
public static Prediction Prediction { get; }
Property Value
Type Description
Prediction
Remarks

NOTE: This is an enterprise edition feature

Methods

| Improve this Doc View Source

AddChangeListener(EventHandler<DatabaseChangedEventArgs>)

Adds a change listener for the changes that occur in this database. Signatures are the same as += style event handlers. The callback will be invoked on a thread pool thread.

Declaration
public ListenerToken AddChangeListener(EventHandler<DatabaseChangedEventArgs> handler)
Parameters
Type Name Description
System.EventHandler<DatabaseChangedEventArgs> handler

The handler to invoke

Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the handler later

Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler is null

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

AddChangeListener(TaskScheduler, EventHandler<DatabaseChangedEventArgs>)

Adds a change listener for the changes that occur in this database. Signatures are the same as += style event handlers, but the callbacks will be called using the specified System.Threading.Tasks.TaskScheduler. If the scheduler is null, the default task scheduler will be used (scheduled via thread pool).

Declaration
public ListenerToken AddChangeListener(TaskScheduler scheduler, EventHandler<DatabaseChangedEventArgs> handler)
Parameters
Type Name Description
System.Threading.Tasks.TaskScheduler scheduler

The scheduler to use when firing the change handler

System.EventHandler<DatabaseChangedEventArgs> handler

The handler to invoke

Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the handler later

Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler is null

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

AddDocumentChangeListener(String, EventHandler<DocumentChangedEventArgs>)

Adds a document change listener for the document with the given ID. The callback will be invoked on a thread pool thread.

Declaration
public ListenerToken AddDocumentChangeListener(string id, EventHandler<DocumentChangedEventArgs> handler)
Parameters
Type Name Description
System.String id

The document ID

System.EventHandler<DocumentChangedEventArgs> handler

The logic to handle the event

Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the listener later

Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler or id is null

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

AddDocumentChangeListener(String, TaskScheduler, EventHandler<DocumentChangedEventArgs>)

Adds a document change listener for the document with the given ID and the System.Threading.Tasks.TaskScheduler that will be used to invoke the callback. If the scheduler is not specified, then the default scheduler will be used (scheduled via thread pool)

Declaration
public ListenerToken AddDocumentChangeListener(string id, TaskScheduler scheduler, EventHandler<DocumentChangedEventArgs> handler)
Parameters
Type Name Description
System.String id

The document ID

System.Threading.Tasks.TaskScheduler scheduler

The scheduler to use when firing the event handler

System.EventHandler<DocumentChangedEventArgs> handler

The logic to handle the event

Returns
Type Description
ListenerToken

A ListenerToken that can be used to remove the listener later

Exceptions
Type Condition
System.ArgumentNullException

Thrown if handler or id is null

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

ChangeEncryptionKey(EncryptionKey)

Sets the encryption key for the database. If null, encryption is removed.

Declaration
public void ChangeEncryptionKey(EncryptionKey key)
Parameters
Type Name Description
EncryptionKey key

The new key to encrypt the database with, or null to remove encryption

Remarks

NOTE: This is an enterprise edition feature

| Improve this Doc View Source

Close()

Close database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

Declaration
public void Close()
Exceptions
Type Condition
CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.Busy if there are still active replicators or query listeners when the close call occurred

| Improve this Doc View Source

Compact()

[DEPRECATED] Compacts the database file by deleting unused attachment files and vacuuming the SQLite database

Declaration
[Obsolete("This method deprecated, please use PerformMaintenance(MaintenanceType type) to compact the database file.")]
public void Compact()
Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

Copy(String, String, DatabaseConfiguration)

Copies a canned database 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 null will be used.

Declaration
public static void Copy(string path, string name, DatabaseConfiguration config)
Parameters
Type Name Description
System.String path

The source database path (i.e. path to the cblite2 folder)

System.String name

The name of the new database to be created

DatabaseConfiguration config

The database configuration for the new database

Exceptions
Type Condition
System.ArgumentNullException

Thrown if path or name are null

CouchbaseException

Thrown if an error condition is returned from LiteCore

| Improve this Doc View Source

CreateIndex(String, IIndex)

Creates an index which could be a value index from ValueIndex(IValueIndexItem[]) or a full-text search index from FullTextIndex(IFullTextIndexItem[]) 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
public void CreateIndex(string name, IIndex index)
Parameters
Type Name Description
System.String name

The index name

IIndex index

The index

Exceptions
Type Condition
System.ArgumentNullException

Thrown if name or index is null

CouchbaseException

Thrown if an error condition is returned from LiteCore

System.InvalidOperationException

Thrown if this method is called after the database is closed

System.NotSupportedException

Thrown if an implementation of IIndex other than one of the library provided ones is used

| Improve this Doc View Source

Delete()

Close and delete the database synchronously. Before closing the database, the active replicators, listeners and live queries will be stopped.

Declaration
public void Delete()
Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore

CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.Busy if there are still active replicators or query listeners when the close call occurred

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

Delete(Document)

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 Delete(Document, ConcurrencyControl) with LastWriteWins

Declaration
public void Delete(Document document)
Parameters
Type Name Description
Document document

The document

Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore

CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.InvalidParameter when trying to save a document into a database other than the one it was previously added to

CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotFound when trying to delete a document that hasn't been saved into a Database yet

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

Delete(Document, ConcurrencyControl)

Deletes the given Document from this database

Declaration
public bool Delete(Document document, ConcurrencyControl concurrencyControl)
Parameters
Type Name Description
Document document

The document to save

ConcurrencyControl concurrencyControl

The rule to use when encountering a conflict in the database

Returns
Type Description
System.Boolean

true if the delete succeeded, false if there was a conflict

Exceptions
Type Condition
CouchbaseException

Thrown if an error condition is returned from LiteCore

CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.InvalidParameter when trying to save a document into a database other than the one it was previously added to

CouchbaseLiteException

Thrown with LiteCore.Interop.C4ErrorCode.NotFound when trying to delete a document that hasn't been saved into a Database yet

System.InvalidOperationException

Thrown if this method is called after the database is closed

| Improve this Doc View Source

Delete(String, String)

Deletes a database of the given name in the given directory. If a null directory is passed then the default directory is searched.

Declaration
public static void Delete(string name, string directory)
Parameters
Type Name Description
System.String name

The database name

System.String directory

The directory where the database is located, or null to check the default directory

Exceptions
Type Condition
System.ArgumentNullException

Thrown if name is null

CouchbaseException

Thrown if an error condition is returned from LiteCore

| Improve this Doc View Source

DeleteIndex(String)

Deletes the index with the given name

Declaration
public void DeleteIndex(string name)
Parameters
Type Name Description
System.String name

The name of the index to delete

| Improve this Doc View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
| Improve this Doc View Source

Equals(Object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
System.Object obj
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)
| Improve this Doc View Source

Exists(String, String)

Checks whether a database of the given name exists in the given directory or not. If a null directory is passed then the default directory is checked

Declaration
public static bool Exists(string name, string directory)
Parameters
Type Name Description
System.String name

The database name

System.String directory

The directory where the database is located

Returns
Type Description
System.Boolean

true if the database exists in the directory, otherwise false

Exceptions
Type Condition
System.ArgumentNullException

Thrown if name is null

CouchbaseException

Thrown if an error condition is returned from LiteCore

| Improve this Doc View Source

Finalize()

Finalizer

Declaration
protected void Finalize()
| Improve this Doc View Source

GetDocument(String)

Gets the Document with the specified ID

Declaration
public Document GetDocument(string id)
Parameters
Type Name Description
System.String id

The ID to use when creating or getting the document

Returns
Type Description
Document

The instantiated document, or null if it does not exist

| Improve this Doc View Source

GetDocumentExpiration(String)

Returns the expiration time of the document. null will be returned if there is no expiration time set

Declaration
public DateTimeOffset? GetDocumentExpiration(string docId)
Parameters
Type Name Description
System.String docId

The ID of the Document

Returns
Type Description
System.Nullable<System.DateTimeOffset>

Nullable expiration timestamp as a System.DateTimeOffset of the document or null if time not set.

Exceptions
Type Condition
CouchbaseLiteException

Throws NOT FOUND error if the document doesn't exist

| Improve this Doc View Source

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()
| Improve this Doc View Source

GetIndexes()

Gets a list of index names that are present in the database

Declaration
public IList<string> GetIndexes()
Returns
Type Description
System.Collections.Generic.IList<System.String>

The list of created index names

| Improve this Doc View Source

InBatch(Action)

Runs the given batch of operations as an atomic unit

Declaration
public void InBatch(Action action)
Parameters
Type Name Description
System.Action action

The System.Action containing the operations.

| Improve this Doc View Source

PerformMaintenance(MaintenanceType)

Performs database maintenance.

Declaration
public void PerformMaintenance(MaintenanceType type)
Parameters
Type Name Description
MaintenanceType type

Maintenance type

| Improve this Doc View Source

Purge(Document)

Purges the given Document from the database. This leaves no trace behind and will not be replicated

Declaration
public void Purge(Document document)
Parameters
Type Name Description
Document document

The document to purge

Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to purge a document from a database other than the one it was previously added to

| Improve this Doc View Source

Purge(String)

Purges the given document id of the Document from the database. This leaves no trace behind and will not be replicated

Declaration
public void Purge(string docId)
Parameters
Type Name Description
System.String docId

The id of the document to purge

| Improve this Doc View Source

RemoveChangeListener(ListenerToken)

Removes a database changed listener by token

Declaration
public void RemoveChangeListener(ListenerToken token)
Parameters
Type Name Description
ListenerToken token

The token received from AddChangeListener(TaskScheduler, EventHandler<DatabaseChangedEventArgs>) and family

| Improve this Doc View Source

Save(MutableDocument)

Saves the given MutableDocument into this database. This call is equivalent to calling Save(MutableDocument, ConcurrencyControl) with a second argument of LastWriteWins

Declaration
public void Save(MutableDocument document)
Parameters
Type Name Description
MutableDocument document

The document to save

Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to save a document into a database other than the one it was previously added to

| Improve this Doc View Source

Save(MutableDocument, ConcurrencyControl)

Saves the given MutableDocument into this database

Declaration
public bool Save(MutableDocument document, ConcurrencyControl concurrencyControl)
Parameters
Type Name Description
MutableDocument document

The document to save

ConcurrencyControl concurrencyControl

The rule to use when encountering a conflict in the database

Returns
Type Description
System.Boolean

true if the save succeeded, false if there was a conflict

Exceptions
Type Condition
System.InvalidOperationException

Thrown when trying to save a document into a database other than the one it was previously added to

| Improve this Doc View Source

Save(MutableDocument, Func<MutableDocument, Document, Boolean>)

Saves a document to the database. When write operations are executed concurrently, and if conflicts occur, conflict handler will be called. Use the handler to directly edit the document.Returning true, will save the document. Returning false, will cancel the save operation.

Declaration
public bool Save(MutableDocument document, Func<MutableDocument, Document, bool> conflictHandler)
Parameters
Type Name Description
MutableDocument document

The document to save

System.Func<MutableDocument, Document, System.Boolean> conflictHandler

The conflict handler block which can be used to resolve it.

Returns
Type Description
System.Boolean

true if the save succeeded, false if there was a conflict

| Improve this Doc View Source

SetDocumentExpiration(String, Nullable<DateTimeOffset>)

Sets an expiration date on a document. After this time, the document will be purged from the database.

Declaration
public bool SetDocumentExpiration(string docId, DateTimeOffset? expiration)
Parameters
Type Name Description
System.String docId

The ID of the Document

System.Nullable<System.DateTimeOffset> expiration

Nullable expiration timestamp as a System.DateTimeOffset, set timestamp to null to remove expiration date time from doc.

Returns
Type Description
System.Boolean

Whether successfully sets an expiration date on the document

Exceptions
Type Condition
CouchbaseLiteException

Throws NOT FOUND error if the document doesn't exist

| Improve this Doc View Source

SetLogLevel(LogDomain, LogLevel)

[DEPRECATED] Sets the log level for the given domains(s)

Declaration
[Obsolete("Currently SetLogLevel will only affect the console logger and not the file logger. Domains will be used as an on/off switch of sorts, and you can no longer set level per domain.")]
public static void SetLogLevel(LogDomain domains, LogLevel level)
Parameters
Type Name Description
LogDomain domains

The log domain(s)

LogLevel level

The log level

| Improve this Doc View Source

ToString()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

Implements

System.IDisposable
  • Improve this Doc
  • View Source
Back to top Generated by DocFX