An Embeddable NoSQL Database Engine

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

Syntax

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

Store records in the database.

Description

Write a new record into the database. If the record does not exists, it is created. Otherwise, it is replaced. That is, the new data overwrite the old data. You can switch to unqlite_kv_append() for an append operation.

unqlite_kv_store_fmt() is a work-alike of the "printf()" family of functions from the standard C library which is used to store 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 xReplace() 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 i,rc;
unqlite *pDb;

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

//Store 100 random records.

for(i = 0 ; i < 100 ; ++i ){

char zKey[12]; //Random generated key

char zData[34]; //Dummy data

// generate the random key

unqlite_util_random_string(pDb,zKey,sizeof(zKey));

// Perform the insertion

rc = unqlite_kv_store(pDb,zKey,sizeof(zKey),zData,sizeof(zData));

if( rc != UNQLITE_OK ){

break;

}

if( i == 79 ){

//Insert a sentinel record

rc = unqlite_kv_store_fmt(pDb,"sentinel",-1,"This record was inserted on %d:%d:%d",14,9,27);

if( rc != UNQLITE_OK ){

break;

}

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);