A CBLDatabase is both a filesystem object and a container for documents. More...

Data Structures
struct	CBLEncryptionKey
	Encryption key specified in a CBLDatabaseConfiguration. More...

struct	CBLDatabaseConfiguration
	Database configuration options. More...

Typedefs
typedef struct CBLDatabase	CBLDatabase
	A connection to an open database. More...

Database configuration
enum	CBLEncryptionAlgorithm : uint32_t { kCBLEncryptionNone = 0 , kCBLEncryptionAES256 }
	Database encryption algorithms (available only in the Enterprise Edition). More...

enum	CBLEncryptionKeySize : uint64_t { kCBLEncryptionKeySizeAES256 = 32 }
	Encryption key sizes (in bytes). More...

CBLDatabaseConfiguration	CBLDatabaseConfiguration_Default (void)
	Returns the default database configuration. More...

bool	CBLEncryptionKey_FromPassword (CBLEncryptionKey *key, FLString password)
	Derives an encryption key from a password. More...

bool	CBLEncryptionKey_FromPasswordOld (CBLEncryptionKey *key, FLString password)
	VOLATILE API: Derives an encryption key from a password in a way that is compatible with certain variants of Couchbase Lite in which a slightly different hashing algorithm is used. More...

Database lifecycle
Opening, closing, and managing open databases.
enum	CBLMaintenanceType : uint32_t { kCBLMaintenanceTypeCompact = 0 , kCBLMaintenanceTypeReindex , kCBLMaintenanceTypeIntegrityCheck , kCBLMaintenanceTypeOptimize , kCBLMaintenanceTypeFullOptimize }
	Maintenance Type used when performing database maintenance. More...

_cbl_warn_unused CBLDatabase *_cbl_nullable	CBLDatabase_Open (FLSlice name, const CBLDatabaseConfiguration _cbl_nullable config, CBLError _cbl_nullable outError)
	Opens a database, or creates it if it doesn't exist yet, returning a new CBLDatabase instance. More...

bool	CBLDatabase_Close (CBLDatabase , CBLError _cbl_nullable outError)
	Closes an open database. More...

static const CBLDatabase *	CBLDatabase_Retain (const CBLDatabase *t)

static void	CBLDatabase_Release (const CBLDatabase *t)

bool	CBLDatabase_Delete (CBLDatabase , CBLError _cbl_nullable outError)
	Closes and deletes a database. More...

bool	CBLDatabase_BeginTransaction (CBLDatabase , CBLError _cbl_nullable outError)
	Begins a transaction. More...

bool	CBLDatabase_EndTransaction (CBLDatabase , bool commit, CBLError _cbl_nullable outError)
	Ends a transaction, either committing or aborting. More...

bool	CBLDatabase_ChangeEncryptionKey (CBLDatabase , const CBLEncryptionKey _cbl_nullable newKey, CBLError *outError)
	Encrypts or decrypts a database, or changes its encryption key. More...

bool	CBLDatabase_PerformMaintenance (CBLDatabase db, CBLMaintenanceType type, CBLError _cbl_nullable outError)
	Performs database maintenance. More...

Database listeners
A database change listener lets you detect changes made to all documents in the default collection. (If you only want to observe specific documents, use a CBLDocumentChangeListener instead.) Note If there are multiple CBLDatabase instances on the same database file, each one's listeners will be notified of changes made by other database instances. Warning Changes made to the database file by other processes will not be notified.
typedef void(*	CBLDatabaseChangeListener) (void _cbl_nullable context, const CBLDatabase db, unsigned numDocs, FLString docIDs[])
	A default collection change listener callback, invoked after one or more documents in the default collection are changed on disk. More...

_cbl_warn_unused CBLListenerToken *	CBLDatabase_AddChangeListener (const CBLDatabase db, CBLDatabaseChangeListener listener, void _cbl_nullable context)
	Registers a default collection change listener callback. More...

Database Extension
bool	CBL_EnableVectorSearch (FLString path, CBLError *_cbl_nullable outError)
	ENTERPRISE EDITION ONLY. More...

Database file operations
These functions operate on database files without opening them.
bool	CBL_DatabaseExists (FLString name, FLString inDirectory)
	Returns true if a database with the given name exists in the given directory. More...

bool	CBL_CopyDatabase (FLString fromPath, FLString toName, const CBLDatabaseConfiguration _cbl_nullable config, CBLError _cbl_nullable outError)
	Copies a database file to a new location, and assigns it a new internal UUID to distinguish it from the original database when replicating. More...

bool	CBL_DeleteDatabase (FLString name, FLString inDirectory, CBLError *_cbl_nullable outError)
	Deletes a database file. More...

Database accessors
Getting information about a database.
FLString	CBLDatabase_Name (const CBLDatabase *)
	Returns the database's name. More...

_cbl_warn_unused FLStringResult	CBLDatabase_Path (const CBLDatabase *)
	Returns the database's full filesystem path, or null slice if the database is closed or deleted. More...

uint64_t	CBLDatabase_Count (const CBLDatabase *)
	Returns the number of documents in the database, or zero if the database is closed or deleted. More...

const CBLDatabaseConfiguration	CBLDatabase_Config (const CBLDatabase *)
	Returns the database's configuration, as given when it was opened. More...

Query Indexes
Query Index Management
bool	CBLDatabase_CreateValueIndex (CBLDatabase db, FLString name, CBLValueIndexConfiguration config, CBLError _cbl_nullable outError)
	Creates a value index. More...

bool	CBLDatabase_CreateFullTextIndex (CBLDatabase db, FLString name, CBLFullTextIndexConfiguration config, CBLError _cbl_nullable outError)
	Creates a full-text index. More...

bool	CBLDatabase_DeleteIndex (CBLDatabase db, FLString name, CBLError _cbl_nullable outError)
	Deletes an index given its name. More...

_cbl_warn_unused FLArray	CBLDatabase_GetIndexNames (CBLDatabase *db)
	Returns the names of the indexes on this database, as a Fleece array of strings. More...

Detailed Description

A CBLDatabase is both a filesystem object and a container for documents.

Typedef Documentation

◆ CBLDatabase

typedef struct CBLDatabase CBLDatabase

A connection to an open database.

◆ CBLDatabaseChangeListener

typedef void(* CBLDatabaseChangeListener) (void *_cbl_nullable context, const CBLDatabase *db, unsigned numDocs, FLString docIDs[])

A default collection change listener callback, invoked after one or more documents in the default collection are changed on disk.

Warning: By default, this listener may be called on arbitrary threads. If your code isn't prepared for that, you may want to use CBLDatabase_BufferNotifications so that listeners will be called in a safe context.; Deprecated : CBLCollectionChangeListener instead.

Parameters

context	An arbitrary value given when the callback was registered.
db	The database that changed.
numDocs	The number of documents that changed (size of the `docIDs` array)
docIDs	The IDs of the documents that changed, as a C array of `numDocs` C strings.

Enumeration Type Documentation

◆ CBLEncryptionAlgorithm

enum CBLEncryptionAlgorithm : uint32_t

Database encryption algorithms (available only in the Enterprise Edition).

Enumerator
kCBLEncryptionNone	No encryption (default)
kCBLEncryptionAES256	AES with 256-bit key.

◆ CBLEncryptionKeySize

enum CBLEncryptionKeySize : uint64_t

Encryption key sizes (in bytes).

Enumerator
kCBLEncryptionKeySizeAES256	Key size for kCBLEncryptionAES256.

◆ CBLMaintenanceType

enum CBLMaintenanceType : uint32_t

Maintenance Type used when performing database maintenance.

Enumerator
kCBLMaintenanceTypeCompact	Compact the database file and delete unused attachments.
kCBLMaintenanceTypeReindex	Rebuild the entire database's indexes.
kCBLMaintenanceTypeIntegrityCheck	Check for the database’s corruption. If found, an error will be returned.
kCBLMaintenanceTypeOptimize	Partially scan indexes to gather database statistics that help optimize queries. This operation is also performed automatically when closing the database.
kCBLMaintenanceTypeFullOptimize	Fully scans all indexes to gather database statistics that help optimize queries. This may take some time, depending on the size of the indexes, but it doesn't have to be redone unless the database changes drastically, or new indexes are created.

Function Documentation

◆ CBL_CopyDatabase()

bool CBL_CopyDatabase	(	FLString	fromPath,
		FLString	toName,
		const CBLDatabaseConfiguration *_cbl_nullable	config,
		CBLError *_cbl_nullable	outError
	)

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.)
outError	On return, will be set to the error that occurred, if applicable.

Note: While a database is open, one or more of its files may be in use. Attempting to copy a file, while it is in use, will fail. We recommend that you close a database before attempting to copy it.

◆ CBL_DatabaseExists()

bool CBL_DatabaseExists	(	FLString	name,
		FLString	inDirectory
	)

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 NULL, `name` must be an absolute or relative path to the database.

◆ CBL_DeleteDatabase()

bool CBL_DeleteDatabase	(	FLString	name,
		FLString	inDirectory,
		CBLError *_cbl_nullable	outError
	)

Deletes a database file.

If the database file is open, an error is returned.

Parameters

name	The database name (without the ".cblite2" extension.)
inDirectory	The directory containing the database. If NULL, `name` must be an absolute or relative path to the database.
outError	On return, will be set to the error that occurred, or a 0 code if no error.

Returns: True if the database was deleted, false if it doesn't exist or deletion failed. (You can tell the last two cases apart by looking at outError.)

◆ CBL_EnableVectorSearch()

bool CBL_EnableVectorSearch	(	FLString	path,
		CBLError *_cbl_nullable	outError
	)

ENTERPRISE EDITION ONLY.

Enables Vector Search extension by specifying the extension path to search for the Vector Search extension library. This function must be called before opening a database that intends to use the vector search extension.

Parameters

path	The file system path of the directory that contains the Vector Search extension library.
outError	On return, will be set to the error that occurred.

Returns: True on success, false if there was an error.

Note: Must be called before opening a database that intends to use the vector search extension.

◆ CBLDatabase_AddChangeListener()

_cbl_warn_unused CBLListenerToken * CBLDatabase_AddChangeListener	(	const CBLDatabase *	db,
		CBLDatabaseChangeListener	listener,
		void *_cbl_nullable	context
	)

Registers a default collection change listener callback.

It will be called after one or more documents are changed on disk.

Warning: Deprecated : Use CBLCollection_AddChangeListener on the default collection instead.

Parameters

db	The database to observe.
listener	The callback to be invoked.
context	An opaque value that will be passed to the callback.

Returns: A token to be passed to CBLListener_Remove when it's time to remove the listener.

◆ CBLDatabase_BeginTransaction()

bool CBLDatabase_BeginTransaction	(	CBLDatabase *	,
		CBLError *_cbl_nullable	outError
	)

Begins a transaction.

You must later call CBLDatabase_EndTransaction to commit or abort the transaction.

Note: Multiple writes are much faster when grouped in a transaction.; Changes will not be visible to other CBLDatabase instances on the same database until the transaction ends.; Transactions can nest. Changes are not committed until the outer transaction ends.

◆ CBLDatabase_ChangeEncryptionKey()

bool CBLDatabase_ChangeEncryptionKey	(	CBLDatabase *	,
		const CBLEncryptionKey *_cbl_nullable	newKey,
		CBLError *	outError
	)

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.

◆ CBLDatabase_Close()

bool CBLDatabase_Close	(	CBLDatabase *	,
		CBLError *_cbl_nullable	outError
	)

Closes an open database.

◆ CBLDatabase_Config()

const CBLDatabaseConfiguration CBLDatabase_Config ( const CBLDatabase * )

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

◆ CBLDatabase_Count()

uint64_t CBLDatabase_Count ( const CBLDatabase * )

Returns the number of documents in the database, or zero if the database is closed or deleted.

Warning: Deprecated : Use CBLCollection_Count on the default collection instead.

◆ CBLDatabase_CreateFullTextIndex()

bool CBLDatabase_CreateFullTextIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLFullTextIndexConfiguration	config,
		CBLError *_cbl_nullable	outError
	)

Creates a full-text index.

Indexes are persistent. If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

Warning: Deprecated : Use CBLCollection_CreateFullTextIndex on the default collection instead.

◆ CBLDatabase_CreateValueIndex()

bool CBLDatabase_CreateValueIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLValueIndexConfiguration	config,
		CBLError *_cbl_nullable	outError
	)

Creates a value index.

Indexes are persistent. If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

Warning: Deprecated : Use CBLCollection_CreateValueIndex on the default collection instead.

◆ CBLDatabase_Delete()

bool CBLDatabase_Delete	(	CBLDatabase *	,
		CBLError *_cbl_nullable	outError
	)

Closes and deletes a database.

If there are any other connections to the database, an error is returned.

◆ CBLDatabase_DeleteIndex()

bool CBLDatabase_DeleteIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLError *_cbl_nullable	outError
	)

Deletes an index given its name.

Warning: Deprecated : Use CBLCollection_DeleteIndex on the default collection instead.

◆ CBLDatabase_EndTransaction()

bool CBLDatabase_EndTransaction	(	CBLDatabase *	,
		bool	commit,
		CBLError *_cbl_nullable	outError
	)

Ends a transaction, either committing or aborting.

◆ CBLDatabase_GetIndexNames()

_cbl_warn_unused FLArray CBLDatabase_GetIndexNames ( CBLDatabase * db )

Returns the names of the indexes on this database, as a Fleece array of strings.

Note: You are responsible for releasing the returned Fleece array.

Warning: Deprecated : Use CBLCollection_GetIndexNames on the default collection instead.

◆ CBLDatabase_Name()

FLString CBLDatabase_Name ( const CBLDatabase * )

Returns the database's name.

◆ CBLDatabase_Open()

_cbl_warn_unused CBLDatabase *_cbl_nullable CBLDatabase_Open	(	FLSlice	name,
		const CBLDatabaseConfiguration *_cbl_nullable	config,
		CBLError *_cbl_nullable	outError
	)

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

It's OK to open the same database file multiple times. Each CBLDatabase 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.)
outError	On failure, the error will be written here.

Returns: The new database object, or NULL on failure.

◆ CBLDatabase_Path()

_cbl_warn_unused FLStringResult CBLDatabase_Path ( const CBLDatabase * )

Returns the database's full filesystem path, or null slice if the database is closed or deleted.

◆ CBLDatabase_PerformMaintenance()

bool CBLDatabase_PerformMaintenance	(	CBLDatabase *	db,
		CBLMaintenanceType	type,
		CBLError *_cbl_nullable	outError
	)

Performs database maintenance.

◆ CBLDatabase_Release()

static void CBLDatabase_Release ( const CBLDatabase * t )

inlinestatic

◆ CBLDatabase_Retain()

static const CBLDatabase * CBLDatabase_Retain ( const CBLDatabase * t )

inlinestatic

◆ CBLDatabaseConfiguration_Default()

CBLDatabaseConfiguration CBLDatabaseConfiguration_Default ( void )

Returns the default database configuration.

◆ CBLEncryptionKey_FromPassword()

bool CBLEncryptionKey_FromPassword	(	CBLEncryptionKey *	key,
		FLString	password
	)

Derives an encryption key from a password.

If your UI uses passwords, call this function to create the key used to encrypt the database. It is designed for security, and deliberately runs slowly to make brute-force attacks impractical.

Parameters

key	The derived AES key will be stored here.
password	The input password, which can be any data.

Returns: True on success, false if there was a problem deriving the key.

◆ CBLEncryptionKey_FromPasswordOld()

bool CBLEncryptionKey_FromPasswordOld	(	CBLEncryptionKey *	key,
		FLString	password
	)

VOLATILE API: Derives an encryption key from a password in a way that is compatible with certain variants of Couchbase Lite in which a slightly different hashing algorithm is used.

The same notes apply as in CBLEncryptionKey_FromPassword

Parameters

key	The derived AES key will be stored here.
password	The input password, which can be any data.

Returns: True on success, false if there was a problem deriving the key.

Data Structures

Typedefs

Database configuration

Database lifecycle

Database listeners

Database Extension

Database file operations

Database accessors

Query Indexes

Detailed Description

Typedef Documentation

◆ CBLDatabase

◆ CBLDatabaseChangeListener

Enumeration Type Documentation

◆ CBLEncryptionAlgorithm

◆ CBLEncryptionKeySize

◆ CBLMaintenanceType

Function Documentation

◆ CBL_CopyDatabase()

◆ CBL_DatabaseExists()

◆ CBL_DeleteDatabase()

◆ CBL_EnableVectorSearch()

◆ CBLDatabase_AddChangeListener()

◆ CBLDatabase_BeginTransaction()

◆ CBLDatabase_ChangeEncryptionKey()

◆ CBLDatabase_Close()

◆ CBLDatabase_Config()

◆ CBLDatabase_Count()

◆ CBLDatabase_CreateFullTextIndex()

◆ CBLDatabase_CreateValueIndex()

◆ CBLDatabase_Delete()

◆ CBLDatabase_DeleteIndex()

◆ CBLDatabase_EndTransaction()

◆ CBLDatabase_GetIndexNames()

◆ CBLDatabase_Name()

◆ CBLDatabase_Open()

◆ CBLDatabase_Path()

◆ CBLDatabase_PerformMaintenance()

◆ CBLDatabase_Release()

◆ CBLDatabase_Retain()

◆ CBLDatabaseConfiguration_Default()

◆ CBLEncryptionKey_FromPassword()

◆ CBLEncryptionKey_FromPasswordOld()