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

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

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

Count

Gets the number of documents in the database

Declaration

public ulong Count { get; }

Property Value

Type	Description
System.UInt64

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

Log

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

Declaration

public static Log Log { get; }

Property Value

Type	Description
Log

Name

Gets the database's name

Declaration

public string Name { get; }

Property Value

Type	Description
System.String

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Dispose()

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

Declaration

public void Dispose()

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)

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

Finalize()

Finalizer

Declaration

protected void Finalize()

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

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

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
System.Int32

Overrides

System.Object.GetHashCode()

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

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.

PerformMaintenance(MaintenanceType)

Performs database maintenance.

Declaration

public void PerformMaintenance(MaintenanceType type)

Parameters

Type	Name	Description
MaintenanceType	type	Maintenance type

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

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

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

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

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

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

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

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

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

System.Object.ToString()

Implements

System.IDisposable