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

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
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 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
EventHandler<DatabaseChangedEventArgs>	handler	The handler to invoke

Returns

Type	Description
ListenerToken	A ListenerToken that can be used to remove the handler later

| 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 . 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
TaskScheduler	scheduler	The scheduler to use when firing the change handler
EventHandler<DatabaseChangedEventArgs>	handler	The handler to invoke

Returns

Type	Description
ListenerToken	A ListenerToken that can be used to remove the handler later

| 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
EventHandler<DocumentChangedEventArgs>	handler	The logic to handle the event

Returns

Type	Description
ListenerToken	A ListenerToken that can be used to remove the listener later

| Improve this Doc View Source

AddDocumentChangeListener(String, TaskScheduler, EventHandler<DocumentChangedEventArgs>)

Adds a document change listener for the document with the given ID and the 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
TaskScheduler	scheduler	The scheduler to use when firing the event handler
EventHandler<DocumentChangedEventArgs>	handler	The logic to handle the event

Returns

Type	Description
ListenerToken	A ListenerToken that can be used to remove the listener later

| 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

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

Remarks

Note: This method will copy the database without changing the encryption key of the original database: the encryption key specified in the given config is the encryption key used for both the original and copied database.To change or add the encryption key for the copied database, call Database.changeEncryptionKey(key) for the copy.

Exceptions

Type	Condition
CouchbaseException	Thrown if an error condition is returned from LiteCore

| Improve this Doc View Source

CreateIndex(String, IndexConfiguration)

Creates a N1QL query index which could be a value index from ValueIndexConfiguration or a full-text search index from FullTextIndexConfiguration 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, IndexConfiguration indexConfig)

Parameters

Type	Name	Description
System.String	name	The index name
IndexConfiguration	indexConfig	The index

Exceptions

Type	Condition
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
CouchbaseException	Thrown if an error condition is returned from LiteCore

| Improve this Doc View Source

CreateQuery(String)

Declaration

public IQuery CreateQuery(string queryExpression)

Parameters

Type	Name	Description
System.String	queryExpression

Returns

Type	Description
IQuery

| 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

| 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

| 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

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

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

GetBlob(Dictionary<String, Object>)

Gets the Blob of a given blob dictionary.

Declaration

public Blob GetBlob(Dictionary<string, object> blobDict)

Parameters

Type	Name	Description
Dictionary<System.String, System.Object>	blobDict	JSON Dictionary represents in the Blob and the value will be validated in IsBlob(IDictionary<String, Object>)

Returns

Type	Description
Blob	The contained value, or `null` if it's digest information doesn’t exist.

Remarks

UNCOMMITTED: Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API. The blobs that are not associated with any documents are/will be removed from the database after compacting the database.

| 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<DateTimeOffset>	Nullable expiration timestamp as a 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

| 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
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
Action	action	The 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

| 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

| 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

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

SaveBlob(Blob)

Save a blob object directly into the database without associating it with any documents.

Declaration

public void SaveBlob(Blob blob)

Parameters

Type	Name	Description
Blob	blob	The blob object will be saved into Database.

Remarks

UNCOMMITTED: Use this API if you are developing Javascript language bindings. If you are developing a native app, you must use the Blob API. The blobs that are not associated with any documents will be removed from the database when compacting the database.

Exceptions

Type	Condition
CouchbaseLiteException	Thrown if an error occurs during the blob save operation.

| 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<DateTimeOffset>	expiration	Nullable expiration timestamp as a , 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

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String