Couchbase Lite C
Couchbase Lite C API
Data Structures | Typedefs
Database

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 CBLDatabaseCBLDatabase_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 CBLListenerTokenCBLDatabase_AddChangeListener (const CBLDatabase *db, CBLDatabaseChangeListener listener, void *_cbl_nullable context)
 Registers a default collection 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, 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...
 

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
contextAn arbitrary value given when the callback was registered.
dbThe database that changed.
numDocsThe number of documents that changed (size of the docIDs array)
docIDsThe 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
fromPathThe full filesystem path to the original database (including extension).
toNameThe new database name (without the ".cblite2" extension.)
configThe database configuration (directory and encryption option.)
outErrorOn 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
nameThe database name (without the ".cblite2" extension.)
inDirectoryThe 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
nameThe database name (without the ".cblite2" extension.)
inDirectoryThe directory containing the database. If NULL, name must be an absolute or relative path to the database.
outErrorOn 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 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
dbThe database to observe.
listenerThe callback to be invoked.
contextAn 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_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
nameThe database name (without the ".cblite2" extension.)
configThe database configuration (directory and encryption option.)
outErrorOn 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
keyThe derived AES key will be stored here.
passwordThe 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
keyThe derived AES key will be stored here.
passwordThe input password, which can be any data.
Returns
True on success, false if there was a problem deriving the key.