An Embeddable NoSQL Database Engine

UnQLite C/C++ API Reference - Writing Data to the Database.

Syntax

int unqlite_kv_append(unqlite *pDb,const void *pKey,int nKeyLen,const void *pData,unqlite_int64 nDataLen);
int unqlite_kv_append_fmt(unqlite *pDb,const void *pKey,int nKeyLen,const char *zFormat,...);

Append data to a database record.

Description

Write a new record into the database. If the record does not exists, it is created. Otherwise, the new data chunk is appended to the end of the old chunk. You can switch to unqlite_kv_store() for an overwrite operation.

unqlite_kv_append_fmt() is a work-alike of the "printf()" family of functions from the standard C library which is used to append a small formatted string.

Records are stored in the database using whatever organization is required by the underlying Key/Value (KV) storage engine. In some cases such as B+Tree, R+Tree, records are stored in a sort order that you may want to define your own comparison function or hash function for the Hash (Default) KV store (either in-memory or disk based). All of these options can be set via unqlite_kv_config().

Parameters

pDb	A pointer to a unQLite Database Handle.
pKey	Record key.
nKeyLen	pKey length. If the nKeyLen argument is less than zero, then pKey is read up to the first zero terminator. If nKeyLen is non-negative, then it is the maximum number of bytes read from pKey.
pData	Record data.
nDataLen	Data length (64-bit integer).

Return value

UNQLITE_OK is returned on success. Any other return value indicates failure such as:

UNQLITE_BUSY: Another thread or process have a reserved or exclusive lock on the database. In which case, the caller should wait until the lock holder relinquish it.

UNQLITE_READ_ONLY: Read-only Key/Value storage engine.

UNQLITE_NOTIMPLEMENTED: The underlying KV storage engine does not implement the xAppend() method.

UNQLITE_PERM: Permission error.

UNQLITE_LIMIT: Journal file record limit reached (An unlikely scenario).

UNQLITE_IOERR: OS specific error. This error is considered harmful and you should perform an immediate rollback via unqlite_rollback().

UNQLITE_NOMEM: Out of memory (Unlikely scenario). This error is considered harmful and you should perform an immediate rollback via unqlite_rollback().

For a human-readable error message, you can extract the database error log via unqlite_config() with a configuration verb set to UNQLITE_CONFIG_ERR_LOG.

Example

Compile this C file for a smart introduction to these interface.

#include <unqlite.h>

int rc;
unqlite *pDb;

// Open our database;
rc = unqlite_open(&pDb,"test.db",UNQLITE_OPEN_CREATE);
if( rc != UNQLITE_OK ){ return; }

//First data chunk .

rc = unqlite_kv_append(pDb,"msg",-1,"Hello, ",7); //msg => 'Hello, '

if( rc == UNQLITE_OK ){

//The second chunk

rc = unqlite_kv_append(pDb,"msg",-1,"Current time is: ",17); //msg => 'Hello, Current time is: '

if( rc == UNQLITE_OK ){

//The last formatted chunk

rc = unqlite_kv_append_fmt(pDb,"msg",-1,"%d:%d:%d",10,16,53); //msg => 'Hello, Current time is: 10:16:53'

}

if( rc != UNQLITE_OK ){

const char *zBuf;

int iLen;

/* Something goes wrong, extract database error log */

unqlite_config(pDb,UNQLITE_CONFIG_ERR_LOG,&zBuf,&iLen);

if( iLen > 0 ){

puts(zBuf);

}

if( rc != UNQLITE_BUSY && rc != UNQLITE_NOTIMPLEMENTED ){

/* Rollback */
unqlite_rollback(pDb);

}

//Auto-commit the transaction and close our handle
unqlite_close(pDb);