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.

Database configuration
enum	CBLEncryptionAlgorithm : uint32_t { kCBLEncryptionNone = 0 , kCBLEncryptionAES256 }
enum	CBLEncryptionKeySize : uint64_t { kCBLEncryptionKeySizeAES256 = 32 }
CBLDatabaseConfiguration	CBLDatabaseConfiguration_Default (void)
	Returns the default database configuration.
bool	CBLEncryptionKey_FromPassword (CBLEncryptionKey *key, FLString password)
	Derives an encryption key from a password.
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.

Database lifecycle
Opening, closing, and managing open databases.
enum	CBLMaintenanceType : uint32_t { kCBLMaintenanceTypeCompact = 0 , kCBLMaintenanceTypeReindex , kCBLMaintenanceTypeIntegrityCheck , kCBLMaintenanceTypeOptimize , kCBLMaintenanceTypeFullOptimize }
_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.
bool	CBLDatabase_Close (CBLDatabase , CBLError _cbl_nullable outError)
	Closes an open database.
CBLINLINE const CBLDatabase *	CBLDatabase_Retain (const CBLDatabase *_cbl_nullable t)
CBLINLINE void	CBLDatabase_Release (const CBLDatabase *_cbl_nullable t)
bool	CBLDatabase_Delete (CBLDatabase , CBLError _cbl_nullable outError)
	Closes and deletes a database.
bool	CBLDatabase_BeginTransaction (CBLDatabase , CBLError _cbl_nullable outError)
	Begins a transaction.
bool	CBLDatabase_EndTransaction (CBLDatabase , bool commit, CBLError _cbl_nullable outError)
	Ends a transaction, either committing or aborting.
bool	CBLDatabase_ChangeEncryptionKey (CBLDatabase , const CBLEncryptionKey _cbl_nullable newKey, CBLError *outError)
	Encrypts or decrypts a database, or changes its encryption key.
bool	CBLDatabase_PerformMaintenance (CBLDatabase db, CBLMaintenanceType type, CBLError _cbl_nullable outError)
	Performs database maintenance.

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

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.
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.
bool	CBL_DeleteDatabase (FLString name, FLString inDirectory, CBLError *_cbl_nullable outError)
	Deletes a database file.

Database accessors
Getting information about a database.
FLString	CBLDatabase_Name (const CBLDatabase *)
	Returns the database's name.
_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.
const CBLDatabaseConfiguration	CBLDatabase_Config (const CBLDatabase *)
	Returns the database's configuration, as given when it was opened.

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.

Enumeration Type Documentation

◆ CBLEncryptionAlgorithm

enum CBLEncryptionAlgorithm : uint32_t

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

◆ CBLEncryptionKeySize

enum CBLEncryptionKeySize : uint64_t

Enumerator
kCBLEncryptionKeySizeAES256	Key size for kCBLEncryptionAES256.

◆ CBLMaintenanceType

enum CBLMaintenanceType : uint32_t

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

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

Ends a transaction, either committing or aborting.

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

CBLINLINE void CBLDatabase_Release ( const CBLDatabase *_cbl_nullable t )

◆ CBLDatabase_Retain()

CBLINLINE const CBLDatabase * CBLDatabase_Retain ( const CBLDatabase *_cbl_nullable t )

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

Database file operations

Database accessors

Detailed Description

Typedef Documentation

◆ CBLDatabase

Enumeration Type Documentation

◆ CBLEncryptionAlgorithm

◆ CBLEncryptionKeySize

◆ CBLMaintenanceType

Function Documentation

◆ CBL_CopyDatabase()

◆ CBL_DatabaseExists()

◆ CBL_DeleteDatabase()

◆ CBL_EnableVectorSearch()

◆ CBLDatabase_BeginTransaction()

◆ CBLDatabase_ChangeEncryptionKey()

◆ CBLDatabase_Close()

◆ CBLDatabase_Config()

◆ CBLDatabase_Delete()

◆ CBLDatabase_EndTransaction()

◆ CBLDatabase_Name()

◆ CBLDatabase_Open()

◆ CBLDatabase_Path()

◆ CBLDatabase_PerformMaintenance()

◆ CBLDatabase_Release()

◆ CBLDatabase_Retain()

◆ CBLDatabaseConfiguration_Default()

◆ CBLEncryptionKey_FromPassword()

◆ CBLEncryptionKey_FromPasswordOld()