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

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 a database. (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 database change listener callback, invoked after one or more documents are changed on disk. More...

_cbl_warn_unused CBLListenerToken *	CBLDatabase_AddChangeListener (const CBLDatabase db, CBLDatabaseChangeListener listener, void _cbl_nullable context)
	Registers a database change listener callback. 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. More...

uint64_t	CBLDatabase_Count (const CBLDatabase *)
	Returns the number of documents in the database. More...

const CBLDatabaseConfiguration	CBLDatabase_Config (const CBLDatabase *)
	Returns the database's configuration, as given when it was opened. 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 database change listener callback, invoked after one or more documents 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.

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.

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

◆ CBLDatabase_AddChangeListener()

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

Registers a database change listener callback.

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

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.

Note: The encryption key is not filled in, for security reasons.

◆ CBLDatabase_Count()

uint64_t CBLDatabase_Count ( const CBLDatabase * )

Returns the number of documents in the database.

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

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

Data Structures

Typedefs

Database configuration

Database lifecycle

Database listeners

Database file operations

Database accessors

Detailed Description

Typedef Documentation

◆ CBLDatabase

◆ CBLDatabaseChangeListener

Enumeration Type Documentation

◆ CBLEncryptionAlgorithm

◆ CBLEncryptionKeySize

◆ CBLMaintenanceType

Function Documentation

◆ CBL_CopyDatabase()

◆ CBL_DatabaseExists()

◆ CBL_DeleteDatabase()

◆ CBLDatabase_AddChangeListener()

◆ CBLDatabase_BeginTransaction()

◆ CBLDatabase_ChangeEncryptionKey()

◆ CBLDatabase_Close()

◆ CBLDatabase_Config()

◆ CBLDatabase_Count()

◆ CBLDatabase_Delete()

◆ CBLDatabase_EndTransaction()

◆ CBLDatabase_Name()

◆ CBLDatabase_Open()

◆ CBLDatabase_Path()

◆ CBLDatabase_PerformMaintenance()

◆ CBLDatabase_Release()

◆ CBLDatabase_Retain()

◆ CBLDatabaseConfiguration_Default()

◆ CBLEncryptionKey_FromPassword()