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

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

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

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 ChangeEncryptionKey(EncryptionKey) for the copy. Furthermore, any Database object that is operating on the source database to be copied should be closed before this call to eliminate the possibility on some platforms of a "resource in use" error.

Exceptions

Type	Condition
System.ArgumentNullException	Thrown if path or name are null
CouchbaseException	Thrown if an error condition is returned from LiteCore

CreateCollection(String, String)

Create a named collection in the specified scope. If the collection already exists, the existing collection will be returned.

Declaration

public Collection CreateCollection(string name, string scope = "_default")

Parameters

Type	Name	Description
System.String	name	The name of the new collection to be created
System.String	scope	The scope of the new collection to be created

Returns

Type	Description
Collection	New collection with the given name and scope

Remarks

None default Collection and Scope Names are allowed to contain the following characters A - Z, a - z, 0 - 9, and the symbols , -, and % and to start with A-Z, a-z, 0-9, and - None default Collection and Scope Names start with and % are prohibited

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

CreateQuery(String)

Creates a Query object from the given SQL++ string.

Declaration

public IQuery CreateQuery(string queryExpression)

Parameters

Type	Name	Description
System.String	queryExpression	SQL++ Expression

Returns

Type	Description
IQuery

Exceptions

Type	Condition
System.ArgumentNullException	Thrown if queryExpression is null
CouchbaseException	Thrown if an error condition is returned from LiteCore
CouchbaseLiteException	Throw if compiling queryExpression returns an error

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

DeleteCollection(String, String)

Delete a collection by name in the specified scope. If the collection doesn't exist, the operation will be no-ops.

Declaration

public void DeleteCollection(string name, string scope = "_default")

Parameters

Type	Name	Description
System.String	name	The name of the collection to be deleted
System.String	scope	The scope of the collection to be deleted

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

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

GetBlob(Dictionary<String, Object>)

Gets the Blob of a given blob dictionary.

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.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

The blobs that are not associated with any documents are/will be removed from the database after compacting the database.

Exceptions

Type	Condition
System.ArgumentException	Throw if the given blob dictionary is not valid.

GetCollection(String, String)

Get a collection in the specified scope by name. If the collection doesn't exist, null will be returned. Note that this will cache after the first retrieval and return the same instance until said instance is disposed. Be careful if using multiple instances because disposing one will invalidate them all.

Declaration

public Collection GetCollection(string name, string scope = "_default")

Parameters

Type	Name	Description
System.String	name	The name of the collection
System.String	scope	The scope of the collection

Returns

Type	Description
Collection	The collection with the given name and scope

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

GetCollections(String)

Get all collections of given Scope name.

Declaration

public IReadOnlyList<Collection> GetCollections(string scope = "_default")

Parameters

Type	Name	Description
System.String	scope	The scope of the collections belong to

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<Collection>	All collections with the given scope name

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

GetDefaultCollection()

Get the default collection. This is a cached object so there is no need to dispose it. If you do, a new one will be created on the next call.

Declaration

public Collection GetDefaultCollection()

Returns

Type	Description
Collection	default collection

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

GetDefaultScope()

Get the default scope.

Declaration

public Scope GetDefaultScope()

Returns

Type	Description
Scope	default scope

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

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
System.Int32

Overrides

System.Object.GetHashCode()

GetScope(String)

Get a scope object by name. As the scope cannot exist by itself without having a collection, the null value will be returned if there is no collection under the given scope’s name. The default scope is an exception, it will always be returned.

Declaration

public Scope GetScope(string name = "_default")

Parameters

Type	Name	Description
System.String	name	The name of the scope

Returns

Type	Description
Scope	scope object with the given scope name

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

GetScopes()

Get scope names that have at least one collection. The default scope is an exception as it will always be listed even it doesn't contain any collection.

Declaration

public IReadOnlyList<Scope> GetScopes()

Returns

Type	Description
System.Collections.Generic.IReadOnlyList<Scope>	scope names of all existing scopes, in the order in which they were created.

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

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

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

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.

ToString()

Declaration

public override string ToString()

Returns

Type	Description
System.String

Overrides

System.Object.ToString()

Implements

System.IDisposable