Data Structures
struct	C4EncryptionKey
	Encryption key specified in a C4DatabaseConfig. More...

struct	C4DatabaseConfig2
	Main database configuration struct (version 2) for use with c4db_openNamed etc. More...

struct	C4UUID

struct	C4CollectionSpec
	Full identifier of a collection in a database, including its scope. More...

Configuration
enum	C4DatabaseFlags : uint32_t { kC4DB_Create = 0x01 , kC4DB_ReadOnly = 0x02 , kC4DB_AutoCompact = 0x04 , kC4DB_VersionVectors = 0x08 , kC4DB_NoUpgrade = 0x20 , kC4DB_NonObservable = 0x40 , kC4DB_FakeVectorClock = 0x80 }

enum	C4EncryptionAlgorithm : uint32_t { kC4EncryptionNone = 0 , kC4EncryptionAES256 }

enum	C4EncryptionKeySize : uint64_t { kC4EncryptionKeySizeAES256 = 32 }

CBL_CORE_API const char *const	kC4DatabaseFilenameExtension
	Filename extension of databases – ".cblite2".

Database Maintenance
enum	C4MaintenanceType : uint32_t { kC4Compact , kC4Reindex , kC4IntegrityCheck , kC4QuickOptimize , kC4FullOptimize }

Configuration
NODISCARD CBL_CORE_API bool	c4key_setPassword (C4EncryptionKey *encryptionKey, C4String password, C4EncryptionAlgorithm alg)
	Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key.

NODISCARD CBL_CORE_API bool	c4key_setPasswordSHA1 (C4EncryptionKey *encryptionKey, C4String password, C4EncryptionAlgorithm alg)
	Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key.

CBL_CORE_API void	c4_setExtensionPath (C4String path)
	Registers a directory path to load extension libraries from, such as Vector Search.

Lifecycle
CBL_CORE_API bool	c4db_exists (C4String name, C4String inDirectory)
	Returns true if a database with the given name exists in the directory.

NODISCARD CBL_CORE_API C4Database *	c4db_openNamed (C4String name, const C4DatabaseConfig2 config, C4Error outError)
	Opens a database given its name (without the ".cblite2" extension) and directory.

NODISCARD CBL_CORE_API C4Database *	c4db_openAgain (C4Database db, C4Error outError)
	Opens a new handle to the same database file as `db`.

NODISCARD CBL_CORE_API bool	c4db_copyNamed (C4String sourcePath, C4String destinationName, const C4DatabaseConfig2 config, C4Error error)
	Copies a prebuilt database from the given source path and places it in the destination directory, with the given name.

NODISCARD CBL_CORE_API bool	c4db_close (C4Database database, C4Error outError)
	Closes the database.

NODISCARD CBL_CORE_API bool	c4db_delete (C4Database database, C4Error outError)
	Closes the database and deletes the file/bundle.

NODISCARD CBL_CORE_API bool	c4db_deleteNamed (C4String dbName, C4String inDirectory, C4Error *outError)
	Deletes the file(s) for the database with the given name in the given directory.

NODISCARD CBL_CORE_API bool	c4db_rekey (C4Database database, const C4EncryptionKey newKey, C4Error *outError)
	Changes a database's encryption key (removing encryption if it's NULL.)

NODISCARD CBL_CORE_API bool	c4_shutdown (C4Error *outError)
	Closes down the storage engines.

Accessors
CBL_CORE_API C4String	c4db_getName (C4Database *)
	Returns the name of the database, as given to `c4db_openNamed`.

CBL_CORE_API C4StringResult	c4db_getPath (C4Database *)
	Returns the path of the database.

CBL_CORE_API const C4DatabaseConfig2 *	c4db_getConfig2 (C4Database *database)
	Returns the configuration the database was opened with.

CBL_CORE_API uint64_t	c4db_getDocumentCount (C4Database *database)
	Returns the number of (undeleted) documents in the database.

CBL_CORE_API C4SequenceNumber	c4db_getLastSequence (C4Database *database)
	Returns the latest sequence number allocated to a revision.

CBL_CORE_API C4Timestamp	c4db_nextDocExpiration (C4Database *database)
	Returns the timestamp at which the next document expiration should take place, or 0 if there are no documents with expiration times.

NODISCARD CBL_CORE_API int64_t	c4db_purgeExpiredDocs (C4Database db, C4Error )
	Purges all documents that have expired.

NODISCARD CBL_CORE_API bool	c4db_getUUIDs (C4Database database, C4UUID publicUUID, C4UUID privateUUID, C4Error outError)
	Returns the database's public and/or private UUIDs.

CBL_CORE_API void	c4db_setExtraInfo (C4Database *database, C4ExtraInfo)
	Associates an arbitrary pointer with this database instance, for client use.

CBL_CORE_API C4ExtraInfo	c4db_getExtraInfo (C4Database *database)
	Returns the C4ExtraInfo associated with this db reference.

Database Maintenance
NODISCARD CBL_CORE_API bool	c4db_maintenance (C4Database database, C4MaintenanceType type, C4Error outError)
	Performs database maintenance.

Transactions
NODISCARD CBL_CORE_API bool	c4db_beginTransaction (C4Database database, C4Error outError)
	Begins a transaction.

NODISCARD CBL_CORE_API bool	c4db_endTransaction (C4Database database, bool commit, C4Error outError)
	Commits or aborts a transaction.

CBL_CORE_API bool	c4db_isInTransaction (C4Database *database)
	Is a transaction active?

Scopes and Collections
#define	kC4DefaultScopeID FLSTR("_default")

#define	kC4DefaultCollectionName FLSTR("_default")

#define	kC4DefaultCollectionSpec ((C4CollectionSpec){kC4DefaultCollectionName, kC4DefaultScopeID})

Detailed Description

Macro Definition Documentation

◆ kC4DefaultCollectionName

#define kC4DefaultCollectionName FLSTR("_default")

◆ kC4DefaultCollectionSpec

#define kC4DefaultCollectionSpec ((C4CollectionSpec){kC4DefaultCollectionName, kC4DefaultScopeID})

◆ kC4DefaultScopeID

#define kC4DefaultScopeID FLSTR("_default")

Enumeration Type Documentation

◆ C4DatabaseFlags

enum C4DatabaseFlags : uint32_t

Enumerator
kC4DB_Create	Create the file if it doesn't exist.
kC4DB_ReadOnly	Open file read-only.
kC4DB_AutoCompact	Enable auto-compaction [UNIMPLEMENTED].
kC4DB_VersionVectors	Upgrade DB to version vectors instead of rev trees.
kC4DB_NoUpgrade	Disable upgrading an older-version database.
kC4DB_NonObservable	Disable database/collection observers, for slightly faster writes.
kC4DB_FakeVectorClock	Use counters instead of timestamps in version vectors (TESTS ONLY)

◆ C4EncryptionAlgorithm

enum C4EncryptionAlgorithm : uint32_t

Enumerator
kC4EncryptionNone	No encryption (default)
kC4EncryptionAES256	AES with 256-bit key [ENTERPRISE EDITION ONLY].

◆ C4EncryptionKeySize

enum C4EncryptionKeySize : uint64_t

Enumerator
kC4EncryptionKeySizeAES256

◆ C4MaintenanceType

enum C4MaintenanceType : uint32_t

Enumerator
kC4Compact	Shrinks the database file by removing any empty pages, and deletes blobs that are no longer referenced by any documents. (Runs SQLite `PRAGMA incremental_vacuum; PRAGMA wal_checkpoint(TRUNCATE)`.)
kC4Reindex	Rebuilds indexes from scratch. Normally never needed, but can be used to help diagnose/troubleshoot cases of database corruption if only indexes are affected. (Runs SQLite `REINDEX`.)
kC4IntegrityCheck	Checks for database corruption, as might be caused by a damaged filesystem, or memory corruption. (Runs SQLite `PRAGMA integrity_check`.)
kC4QuickOptimize	Quickly updates database statistics that may help optimize queries that have been run by this Database since it was opened. The more queries that have been run, the more effective this will be, but it tries to do its work quickly by scanning only portions of indexes. This operation is also performed automatically by c4db_close. (Runs SQLite `PRAGMA analysis_limit=400; PRAGMA optimize`.)
kC4FullOptimize	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. (Runs SQLite `PRAGMA analysis_limit=0; ANALYZE`.)

Function Documentation

◆ c4_setExtensionPath()

CBL_CORE_API void c4_setExtensionPath ( C4String path )

Registers a directory path to load extension libraries from, such as Vector Search.

Must be called before opening a database that will use an extension.

◆ c4_shutdown()

NODISCARD CBL_CORE_API bool c4_shutdown ( C4Error * outError )

Closes down the storage engines.

Must close all databases first. You don't generally need to do this, but it can be useful in tests.

◆ c4db_beginTransaction()

NODISCARD CBL_CORE_API bool c4db_beginTransaction	(	C4Database *	database,
		C4Error *	outError
	)

Begins a transaction.

Transactions can nest; only the first call actually creates a database transaction.

◆ c4db_close()

NODISCARD CBL_CORE_API bool c4db_close	(	C4Database *	database,
		C4Error *	outError
	)

Closes the database.

Does not free the handle, although any operation other than c4db_release() will fail with an error.

◆ c4db_copyNamed()

NODISCARD CBL_CORE_API bool c4db_copyNamed	(	C4String	sourcePath,
		C4String	destinationName,
		const C4DatabaseConfig2 *	config,
		C4Error *	error
	)

Copies a prebuilt database from the given source path and places it in the destination directory, with the given name.

If a database already exists there, it will be overwritten. However if there is a failure, the original database will be restored as if nothing happened.

Parameters

sourcePath	The path to the database to be copied.
destinationName	The name (without filename extension) of the database to create.
config	Database configuration (including destination directory.)
error	On failure, error info will be written here.

Returns: True on success, false on failure.

◆ c4db_delete()

NODISCARD CBL_CORE_API bool c4db_delete	(	C4Database *	database,
		C4Error *	outError
	)

Closes the database and deletes the file/bundle.

Does not free the handle, although any operation other than c4db_release() will fail with an error.

◆ c4db_deleteNamed()

NODISCARD CBL_CORE_API bool c4db_deleteNamed	(	C4String	dbName,
		C4String	inDirectory,
		C4Error *	outError
	)

Deletes the file(s) for the database with the given name in the given directory.

All C4Databases at that path must be closed first or an error will result. Returns false, with no error, if the database doesn't exist.

◆ c4db_endTransaction()

NODISCARD CBL_CORE_API bool c4db_endTransaction	(	C4Database *	database,
		bool	commit,
		C4Error *	outError
	)

Commits or aborts a transaction.

If there have been multiple calls to beginTransaction, it takes the same number of calls to endTransaction to actually end the transaction; only the last one commits or aborts the database transaction.

◆ c4db_exists()

CBL_CORE_API bool c4db_exists	(	C4String	name,
		C4String	inDirectory
	)

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

◆ c4db_getConfig2()

CBL_CORE_API const C4DatabaseConfig2 * c4db_getConfig2 ( C4Database * database )

Returns the configuration the database was opened with.

◆ c4db_getDocumentCount()

CBL_CORE_API uint64_t c4db_getDocumentCount ( C4Database * database )

Returns the number of (undeleted) documents in the database.

◆ c4db_getExtraInfo()

CBL_CORE_API C4ExtraInfo c4db_getExtraInfo ( C4Database * database )

Returns the C4ExtraInfo associated with this db reference.

◆ c4db_getLastSequence()

CBL_CORE_API C4SequenceNumber c4db_getLastSequence ( C4Database * database )

Returns the latest sequence number allocated to a revision.

◆ c4db_getName()

CBL_CORE_API C4String c4db_getName ( C4Database * )

Returns the name of the database, as given to c4db_openNamed.

This is the filename without the ".cblite2" extension.

◆ c4db_getPath()

CBL_CORE_API C4StringResult c4db_getPath ( C4Database * )

Returns the path of the database.

◆ c4db_getUUIDs()

NODISCARD CBL_CORE_API bool c4db_getUUIDs	(	C4Database *	database,
		C4UUID *	publicUUID,
		C4UUID *	privateUUID,
		C4Error *	outError
	)

Returns the database's public and/or private UUIDs.

(Pass NULL for ones you don't want.)

◆ c4db_isInTransaction()

CBL_CORE_API bool c4db_isInTransaction ( C4Database * database )

Is a transaction active?

◆ c4db_maintenance()

NODISCARD CBL_CORE_API bool c4db_maintenance	(	C4Database *	database,
		C4MaintenanceType	type,
		C4Error *	outError
	)

Performs database maintenance.

For more detail, see the descriptions of the C4MaintenanceType enum constants.

◆ c4db_nextDocExpiration()

CBL_CORE_API C4Timestamp c4db_nextDocExpiration ( C4Database * database )

Returns the timestamp at which the next document expiration should take place, or 0 if there are no documents with expiration times.

◆ c4db_openAgain()

NODISCARD CBL_CORE_API C4Database * c4db_openAgain	(	C4Database *	db,
		C4Error *	outError
	)

Opens a new handle to the same database file as db.

The new connection is completely independent and can be used on another thread.

◆ c4db_openNamed()

NODISCARD CBL_CORE_API C4Database * c4db_openNamed	(	C4String	name,
		const C4DatabaseConfig2 *	config,
		C4Error *	outError
	)

Opens a database given its name (without the ".cblite2" extension) and directory.

◆ c4db_purgeExpiredDocs()

NODISCARD CBL_CORE_API int64_t c4db_purgeExpiredDocs	(	C4Database *	db,
		C4Error *
	)

Purges all documents that have expired.

Warning: This is generally unnecessary, since the background housekeeping task will do it. You might want to call this if you require the purge to happen synchronously, just before copying the database file or something like that.)

Returns: The number of documents purged, or -1 on error.

◆ c4db_rekey()

NODISCARD CBL_CORE_API bool c4db_rekey	(	C4Database *	database,
		const C4EncryptionKey *	newKey,
		C4Error *	outError
	)

Changes a database's encryption key (removing encryption if it's NULL.)

◆ c4db_setExtraInfo()

CBL_CORE_API void c4db_setExtraInfo	(	C4Database *	database,
		C4ExtraInfo
	)

Associates an arbitrary pointer with this database instance, for client use.

For example, this could be a reference to the higher-level object wrapping the database.

The destructor field of the C4ExtraInfo can be used to provide a function that will be called when the C4Database is freed, so it can free any resources associated with the pointer.

◆ c4key_setPassword()

NODISCARD CBL_CORE_API bool c4key_setPassword	(	C4EncryptionKey *	encryptionKey,
		C4String	password,
		C4EncryptionAlgorithm	alg
	)

Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key.

Parameters

encryptionKey	The raw key will be stored here.
password	The password string.
alg	The encryption algorithm to use. Must not be kC4EncryptionNone.

Returns: True on success, false on failure

◆ c4key_setPasswordSHA1()

NODISCARD CBL_CORE_API bool c4key_setPasswordSHA1	(	C4EncryptionKey *	encryptionKey,
		C4String	password,
		C4EncryptionAlgorithm	alg
	)

Stores a password into a C4EncryptionKey, by using the key-derivation algorithm PBKDF2 to securely convert the password into a raw binary key.

Uses SHA1 for the hashing function as employed by PBKDF2.

Parameters

encryptionKey	The raw key will be stored here.
password	The password string.
alg	The encryption algorithm to use. Must not be kC4EncryptionNone.

Returns: True on success, false on failure

Variable Documentation

◆ kC4DatabaseFilenameExtension

CBL_CORE_API const char* const kC4DatabaseFilenameExtension

extern

Filename extension of databases – ".cblite2".

Includes the period.

Data Structures

Configuration

Database Maintenance

Configuration

Lifecycle

Accessors

Database Maintenance

Transactions

Scopes and Collections

Detailed Description

Macro Definition Documentation

◆ kC4DefaultCollectionName

◆ kC4DefaultCollectionSpec

◆ kC4DefaultScopeID

Enumeration Type Documentation

◆ C4DatabaseFlags

◆ C4EncryptionAlgorithm

◆ C4EncryptionKeySize

◆ C4MaintenanceType

Function Documentation

◆ c4_setExtensionPath()

◆ c4_shutdown()

◆ c4db_beginTransaction()

◆ c4db_close()

◆ c4db_copyNamed()

◆ c4db_delete()

◆ c4db_deleteNamed()

◆ c4db_endTransaction()

◆ c4db_exists()

◆ c4db_getConfig2()

◆ c4db_getDocumentCount()

◆ c4db_getExtraInfo()

◆ c4db_getLastSequence()

◆ c4db_getName()

◆ c4db_getPath()

◆ c4db_getUUIDs()

◆ c4db_isInTransaction()

◆ c4db_maintenance()

◆ c4db_nextDocExpiration()

◆ c4db_openAgain()

◆ c4db_openNamed()

◆ c4db_purgeExpiredDocs()

◆ c4db_rekey()

◆ c4db_setExtraInfo()

◆ c4key_setPassword()

◆ c4key_setPasswordSHA1()

Variable Documentation

◆ kC4DatabaseFilenameExtension