LiteCore
Couchbase Lite cross-platform core implementation
Loading...
Searching...
No Matches
Databases

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)
 
CBL_CORE_API bool c4_enableExtension (C4String name, C4String extensionPath, C4Error *outError)
 Asks LiteCore to look for and validate the presence of an extension given the name of the extension and the path in which it is supposed to reside.
 

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 C4Databasec4db_openNamed (C4String name, const C4DatabaseConfig2 *config, C4Error *outError)
 Opens a database given its name (without the ".cblite2" extension) and directory.
 
NODISCARD CBL_CORE_API C4Databasec4db_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 C4DatabaseConfig2c4db_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_enableExtension()

CBL_CORE_API bool c4_enableExtension ( C4String name,
C4String extensionPath,
C4Error * outError )

Asks LiteCore to look for and validate the presence of an extension given the name of the extension and the path in which it is supposed to reside.

It makes an attempt to only check things that have the possibility of being corrected by the user (i.e. if there is a bug in the extension and it cannot load functionally that won't be caught)

Note
This function is not thread-safe.
Parameters
nameThe name of the extension (corresponds to the filename without the extension or "lib" prefix)
extensionPathThe path in which the extension should be found
outErrorOn failure, will store the error.
Returns
True on success, false on failure

◆ c4_setExtensionPath()

CBL_CORE_API void c4_setExtensionPath ( C4String path)

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

Note
The caller must use a lock for Database when this function is called.

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

Note
The caller must use a lock for Database when this function is called.

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

Note
This function is thread-safe.
Parameters
sourcePathThe path to the database to be copied.
destinationNameThe name (without filename extension) of the database to create.
configDatabase configuration (including destination directory.)
errorOn 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. All C4Databases at that path must be closed first or an error will result.

Note
This function is thread-safe.

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

Note
This function is thread-safe.

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

Note
The caller must use a lock for Database when this function is called.

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

Note
This function is thread-safe.

◆ c4db_getDocumentCount()

CBL_CORE_API uint64_t c4db_getDocumentCount ( C4Database * database)

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

Note
The caller must use a lock for Database when this function is called.

◆ c4db_getExtraInfo()

CBL_CORE_API C4ExtraInfo c4db_getExtraInfo ( C4Database * database)

Returns the C4ExtraInfo associated with this db reference.

Note
The caller must use a lock for Database when this function is called.

◆ c4db_getLastSequence()

CBL_CORE_API C4SequenceNumber c4db_getLastSequence ( C4Database * database)

Returns the latest sequence number allocated to a revision.

Note
The caller must use a lock for Database when this function is called.

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

Note
This function is thread-safe.

◆ c4db_getPath()

Returns the path of the database.

Note
This function is thread-safe.

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

Note
The caller must use a lock for Database when this function is called.

◆ c4db_isInTransaction()

CBL_CORE_API bool c4db_isInTransaction ( C4Database * database)

Is a transaction active?

Note
The caller must use a lock for Database when this function is called.

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

Note
The caller must use a lock for Database when this function is called.

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

Note
The caller must use a lock for Database when this function is called.

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

Note
This function is thread-safe.

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

Note
This function is thread-safe.

◆ c4db_purgeExpiredDocs()

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

Purges all documents that have expired.

Note
The caller must use a lock for Database when this function is called.
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.)

Note
The caller must use a lock for Database when this function is called.
All other C4Databases at that path must be closed first or an error will result.

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

Note
The caller must use a lock for Database when this function is called.

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

Note
This function is thread-safe.
Parameters
encryptionKeyThe raw key will be stored here.
passwordThe password string.
algThe 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.

Note
This function is thread-safe.
Parameters
encryptionKeyThe raw key will be stored here.
passwordThe password string.
algThe 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.