A Couchbase Lite database, which is a container for collections of documents. More...

#include <cbl++/Database.hh>

Inheritance diagram for cbl::Database:

Public Types
using	NotificationsReadyCallback = std::function<void(Database)>

Public Member Functions
	Database (std::string_view name)
	Opens a database, or creates it if it doesn't exist yet, returning a new Database instance.
	Database (std::string_view name, const DatabaseConfiguration &config)
	Opens a database, or creates it if it doesn't exist yet, returning a new Database instance.
void	close ()
	Closes an open database.
void	deleteDatabase ()
	Closes and deletes a database.
void	performMaintenance (CBLMaintenanceType type)
	Performs database maintenance.
void	changeEncryptionKey (const EncryptionKey *_Nullable newKey)
	Encrypts or decrypts a database, or changes its encryption key.
std::string	name () const
	Returns the database's name.
std::string	path () const
	Returns the database's full filesystem path, or an empty string if the database is closed or deleted.
DatabaseConfiguration	config () const
	Returns the database's configuration, as given when it was opened.
Blob	getBlob (fleece::Dict properties) const
	Get a Blob from the database using the Blob properties.
void	saveBlob (const Blob &blob)
	Save a new Blob object into the database without associating it with any documents.
fleece::MutableArray	getScopeNames () const
	Returns the names of all existing scopes in the database.
fleece::MutableArray	getCollectionNames (std::string_view scopeName=(std::string_view) slice(kCBLDefaultScopeName)) const
	Returns the names of all collections in the scope.
Collection	getCollection (std::string_view collectionName, std::optional< std::string_view > scopeName=std::nullopt) const
	Returns the existing collection with the given name and scope.
Collection	createCollection (std::string_view collectionName, std::optional< std::string_view > scopeName=std::nullopt)
	Create a new collection.
void	deleteCollection (std::string_view collectionName, std::optional< std::string_view > scopeName=std::nullopt)
	Delete an existing collection.
Collection	getDefaultCollection () const
	Returns the default collection.
Query	createQuery (QueryLanguage language, std::string_view queryString)
	Creates a new query by compiling the input string.
void	bufferNotifications (NotificationsReadyCallback callback)
	Switches the database to buffered-notification mode.
void	sendNotifications ()
	Immediately issues all pending notifications for this database, by calling their listener callbacks.
	~Database ()
	Releases the underlying database handle.
	Database () noexcept
	Constructs a null reference (one that points to no object).
Database &	operator= (std::nullptr_t)
	Releases the underlying object and resets this to a null reference.
bool	valid () const
	Returns true if this references an object, or false if it is a null reference.
	operator bool () const
	Returns true if this references an object (same as valid).
bool	operator== (const Database &other) const
	Returns true if both sides reference the same object, or are both null references.
bool	operator!= (const Database &other) const
	Returns true if the two sides reference different objects.
CBLDatabase *_Nullable	ref () const
	Returns a pointer to the underlying C object (CBLDatabase), or NULL if this is a null reference.
	Database (const Database &other) noexcept
	Copy constructor.
	Database (Database &&other) noexcept
	Move constructor.
Database &	operator= (const Database &other) noexcept
	Copy assignment.
Database &	operator= (Database &&other) noexcept
	Move assignment.
void	clear ()
	Releases the underlying C CBLDatabase handle and drops the buffered-notification callback.

Static Public Member Functions
static bool	exists (std::string_view name, std::optional< std::string_view > inDirectory=std::nullopt)
	Returns true if a database with the given name exists in the given directory.
static void	copyDatabase (std::string_view fromPath, std::string_view toName)
	Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating.
static void	copyDatabase (std::string_view fromPath, std::string_view toName, const DatabaseConfiguration &config)
	Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating.
static void	deleteDatabase (std::string_view name, std::optional< std::string_view > inDirectory=std::nullopt)
	Deletes a database file.

Protected Member Functions
	Database (CBLDatabase *_Nullable ref)
	(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Friends
class	Collection
class	Scope

Detailed Description

A Couchbase Lite database, which is a container for collections of documents.

Member Typedef Documentation

◆ NotificationsReadyCallback

using cbl::Database::NotificationsReadyCallback = std::function<void(Database)>

Constructor & Destructor Documentation

◆ Database() [1/6]

cbl::Database::Database ( std::string_view name )

inline

Opens a database, or creates it if it doesn't exist yet, returning a new Database instance.

It's OK to open the same database file multiple times. Each Database instance is independent of the others (and must be separately closed and released.)

Parameters

name	The database name (without the ".cblite2" extension.)

◆ Database() [2/6]

cbl::Database::Database	(	std::string_view	name,
		const DatabaseConfiguration &	config )

inline

Opens a database, or creates it if it doesn't exist yet, returning a new Database instance.

It's OK to open the same database file multiple times. Each Database instance is independent of the others (and must be separately closed and released.)

Parameters

name	The database name (without the ".cblite2" extension.)
config	The database configuration (directory and encryption option.)

◆ ~Database()

cbl::Database::~Database ( )

inline

Releases the underlying database handle.

The database remains open if other Database references to it exist.

◆ Database() [3/6]

cbl::Database::Database ( )

inlinenoexcept

Constructs a null reference (one that points to no object).

◆ Database() [4/6]

cbl::Database::Database ( CBLDatabase *_Nullable ref )

inlineexplicitprotected

(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

◆ Database() [5/6]

cbl::Database::Database ( const Database & other )

inlinenoexcept

Copy constructor.

Both *this and other refer to the same underlying CBLDatabase handle (its refcount is incremented) and share the buffered-notification callback state.

◆ Database() [6/6]

cbl::Database::Database ( Database && other )

inlinenoexcept

Move constructor.

Takes over other's CBLDatabase handle and buffered-notification callback state, leaving other empty.

Member Function Documentation

◆ bufferNotifications()

void cbl::Database::bufferNotifications ( NotificationsReadyCallback callback )

inline

Switches the database to buffered-notification mode.

Notifications for objects belonging to this database (documents, queries, replicators, and of course the database) will not be called immediately; your NotificationsReadyCallback will be called instead.

Parameters

callback The function to be called when a notification is available.

◆ changeEncryptionKey()

void cbl::Database::changeEncryptionKey ( const EncryptionKey *_Nullable newKey )

inline

Encrypts or decrypts a database, or changes its encryption key.

If newKey is NULL, or its algorithm is kCBLEncryptionNone, the database will be decrypted. Otherwise the database will be encrypted with that key; if it was already encrypted, it will be re-encrypted with the new key.

◆ clear()

void cbl::Database::clear ( )

inline

Releases the underlying C CBLDatabase handle and drops the buffered-notification callback.

After this call the object is empty (its operator bool returns false).

Note: Other Database references to the same database file remain valid.

◆ close()

void cbl::Database::close ( )

inline

Closes an open database.

◆ config()

DatabaseConfiguration cbl::Database::config ( ) const

inline

Returns the database's configuration, as given when it was opened.

◆ copyDatabase() [1/2]

void cbl::Database::copyDatabase	(	std::string_view	fromPath,
		std::string_view	toName )

inlinestatic

Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating.

Parameters

fromPath	The full filesystem path to the original database (including extension).
toName	The new database name (without the ".cblite2" extension.)

◆ copyDatabase() [2/2]

void cbl::Database::copyDatabase	(	std::string_view	fromPath,
		std::string_view	toName,
		const DatabaseConfiguration &	config )

inlinestatic

Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating.

Parameters

fromPath	The full filesystem path to the original database (including extension).
toName	The new database name (without the ".cblite2" extension.)
config	The database configuration (directory and encryption option.)

◆ createCollection()

Collection cbl::Database::createCollection	(	std::string_view	collectionName,
		std::optional< std::string_view >	scopeName = std::nullopt )

inline

Create a new collection.

The naming rules of the collections and scopes are as follows:

Must be between 1 and 251 characters in length.
Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.
Cannot start with _ or %.
Both scope and collection names are case sensitive.
Note
If the collection already exists, the existing collection will be returned.

Parameters

collectionName The name of the collection.

scopeName The name of the scope (optional). If not supplied, the default scope name will be used.

Returns
A Collection instance.

◆ createQuery()

Query cbl::Database::createQuery	(	QueryLanguage	language,
		std::string_view	queryString )

inline

Creates a new query by compiling the input string.

This is fast, but not instantaneous. If you need to run the same query many times, keep the Query object around instead of compiling it each time. If you need to run related queries with only some values different, create one query with placeholder parameter(s), and substitute the desired value(s) with Query::setParameters(fleece::Dict parameters) each time you run the query.

Parameters

language	The query language, JSON or N1QL.
queryString	The query string.

Returns: The new query object.

◆ deleteCollection()

void cbl::Database::deleteCollection	(	std::string_view	collectionName,
		std::optional< std::string_view >	scopeName = std::nullopt )

inline

Delete an existing collection.

Note: The default collection cannot be deleted.

Parameters

collectionName	The name of the collection.
scopeName	The name of the scope (optional). If not supplied, the default scope name will be used.

◆ deleteDatabase() [1/2]

void cbl::Database::deleteDatabase ( )

inline

Closes and deletes a database.

◆ deleteDatabase() [2/2]

void cbl::Database::deleteDatabase	(	std::string_view	name,
		std::optional< std::string_view >	inDirectory = std::nullopt )

inlinestatic

Deletes a database file.

If the database file is open, an error will be thrown.

Parameters

name	The database name (without the ".cblite2" extension.)
inDirectory	The directory containing the database(optional), If not provided, name must be an absolute or relative path to the database.

◆ exists()

bool cbl::Database::exists	(	std::string_view	name,
		std::optional< std::string_view >	inDirectory = std::nullopt )

inlinestatic

Returns true if a database with the given name exists in the given directory.

Parameters

name	The database name (without the ".cblite2" extension.)
inDirectory	The directory containing the database. If not provided, name must be an absolute or relative path to the database.

◆ getBlob()

Blob cbl::Database::getBlob ( fleece::Dict properties ) const

inline

Get a Blob from the database using the Blob properties.

The Blob properties is a blob's metadata containing two required fields which are a special marker property "@type":"blob", and property digest whose value is a hex SHA-1 digest of the blob's data. The other optional properties are length and content_type. To obtain the Blob properties from a Blob, call Blob::properties function.

Parameters

properties The properties for getting the Blob object.

Returns: The Blob, or a falsy Blob if no blob with the given digest exists.

Exceptions

cbl::Error On a database error (such as malformed blob properties). Note a non-existent blob is not an error — that returns a falsy Blob rather than throwing.

◆ getCollection()

Collection cbl::Database::getCollection	(	std::string_view	collectionName,
		std::optional< std::string_view >	scopeName = std::nullopt ) const

inline

Returns the existing collection with the given name and scope.

Parameters

collectionName	The name of the collection.
scopeName	The name of the scope (optional). If not supplied, the default scope name will be used.

Returns: The Collection, or a falsy Collection if it doesn't exist.

Exceptions

cbl::Error On a database error. Note a non-existent collection is not an error — that returns a falsy Collection rather than throwing.

◆ getCollectionNames()

fleece::MutableArray cbl::Database::getCollectionNames ( std::string_view scopeName = (std::string_view)slice(kCBLDefaultScopeName) ) const

inline

Returns the names of all collections in the scope.

Parameters

scopeName The name of the scope.

Returns: The names of all collections in the scope, or throws if an error occurred.

◆ getDefaultCollection()

Collection cbl::Database::getDefaultCollection ( ) const

inline

Returns the default collection.

◆ getScopeNames()

fleece::MutableArray cbl::Database::getScopeNames ( ) const

inline

Returns the names of all existing scopes in the database.

The scope exists when there is at least one collection created under the scope.

Note: The default scope will always exist, containing at least the default collection.

Returns: The names of all existing scopes in the database, or throws if an error occurred.

◆ name()

std::string cbl::Database::name ( ) const

inline

Returns the database's name.

◆ operator bool()

cbl::Database::operator bool ( ) const

inlineexplicit

Returns true if this references an object (same as valid).

◆ operator!=()

bool cbl::Database::operator!= ( const Database & other ) const

inline

Returns true if the two sides reference different objects.

◆ operator=() [1/3]

Database & cbl::Database::operator= ( const Database & other )

inlinenoexcept

Copy assignment.

Releases the currently-referenced handle (if any), then makes *this refer to the same CBLDatabase as other (refcount incremented) and share its buffered-notification callback state.

◆ operator=() [2/3]

Database & cbl::Database::operator= ( Database && other )

inlinenoexcept

Move assignment.

Releases the currently-referenced handle (if any), then takes over other's CBLDatabase handle and buffered-notification callback state; other is left empty.

◆ operator=() [3/3]

Database & cbl::Database::operator= ( std::nullptr_t )

inline

Releases the underlying object and resets this to a null reference.

◆ operator==()

bool cbl::Database::operator== ( const Database & other ) const

inline

Returns true if both sides reference the same object, or are both null references.

◆ path()

std::string cbl::Database::path ( ) const

inline

Returns the database's full filesystem path, or an empty string if the database is closed or deleted.

◆ performMaintenance()

void cbl::Database::performMaintenance ( CBLMaintenanceType type )

inline

Performs database maintenance.

Parameters

type	The database maintenance type.

◆ ref()

CBLDatabase *_Nullable cbl::Database::ref ( ) const

inline

Returns a pointer to the underlying C object (CBLDatabase), or NULL if this is a null reference.

◆ saveBlob()

void cbl::Database::saveBlob ( const Blob & blob )

inline

Save a new Blob object into the database without associating it with any documents.

The properties of the saved Blob object will include information necessary for referencing the Blob object in the properties of the document to be saved into the database.

Normally you do not need to use this function unless you are in the situation (e.g. developing javascript binding) that you cannot retain the CBLBlob object until the document containing the CBLBlob object is successfully saved into the database.

Note: The saved Blob objects that are not associated with any documents will be removed from the database when compacting the database.

Parameters

blob	The Blob to save.

◆ sendNotifications()

void cbl::Database::sendNotifications ( )

inline

Immediately issues all pending notifications for this database, by calling their listener callbacks.

◆ valid()

bool cbl::Database::valid ( ) const

inline

Returns true if this references an object, or false if it is a null reference.

◆ Collection

friend class Collection

friend

◆ Scope

friend class Scope

friend

The documentation for this class was generated from the following files:

include/cbl++/Database.hh
include/cbl++/Blob.hh
include/cbl++/Collection.hh
include/cbl++/Query.hh

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ NotificationsReadyCallback

Constructor & Destructor Documentation

◆ Database() [1/6]

◆ Database() [2/6]

◆ ~Database()

◆ Database() [3/6]

◆ Database() [4/6]

◆ Database() [5/6]

◆ Database() [6/6]

Member Function Documentation

◆ bufferNotifications()

◆ changeEncryptionKey()

◆ clear()

◆ close()

◆ config()

◆ copyDatabase() [1/2]

◆ copyDatabase() [2/2]

◆ createCollection()

◆ createQuery()

◆ deleteCollection()

◆ deleteDatabase() [1/2]

◆ deleteDatabase() [2/2]

◆ exists()

◆ getBlob()

◆ getCollection()

◆ getCollectionNames()

◆ getDefaultCollection()

◆ getScopeNames()

◆ name()

◆ operator bool()

◆ operator!=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ path()

◆ performMaintenance()

◆ ref()

◆ saveBlob()

◆ sendNotifications()

◆ valid()

Friends And Related Symbol Documentation

◆ Collection

◆ Scope