Skip to content

DB API

The DB library is a high performance NoSQL database for embedded applications. It supports fast, flexible local data access and transparent synchronization of data to the cloud. It is modeled after DynamoDB and the OneTable access library.

DB is a NoSQL database where database items items are documents of arbitrary complexity. Data items are implemented as JSON documents and are organized into entity tables. Application entities are defined via an entity schema that specifies data fields and attributes.

DB uses Red/black binary search indexes and has controllable local persistency to disk and to the cloud on a per-table basis.

Extensions

Db Embedded Database based on DynamoDB.

Functions

voiddbAddContext(Db *db, cchar *name, cchar *value)
 Add global context properties.
voiddbClose(Db *db)
 Close a database.
const DbItem*dbCreate(Db *db, cchar *model, Json *props, DbParams *params)
 Create a new item.
cchar*dbField(const DbItem *item, cchar *fieldName)
 Fetch a field value from an item as a string.
booldbFieldBool(const DbItem *item, cchar *fieldName)
 Fetch a field value from an item as a boolean.
TimedbFieldDate(const DbItem *item, cchar *fieldName)
 Fetch a field value from an item as a date.
doubledbFieldDouble(const DbItem *item, cchar *fieldName)
 Fetch a field value from an item as a double.
int64dbFieldNumber(const DbItem *item, cchar *fieldName)
 Fetch a field value from an item as a number (64 bit).
DbGrid*dbFind(Db *db, cchar *model, Json *props, DbParams *params)
 Find matching items in the database.
const DbItem*dbFindOne(Db *db, cchar *model, Json *props, DbParams *params)
 Find the first matching item.
voiddbFreeGrid(DbGrid *grid)
 Free a grid returned by dbFind.
const DbItem*dbGet(Db *db, cchar *model, Json *props, DbParams *params)
 Read a matching item from the database.
cchar*dbGetField(Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params)
 Get a field from a matching item from the database.
Json*dbJson(cchar *str)
 Parse a string into Json properties.
Json*dbJsonProps(cchar *props[])
 Convert a list of keyword / value pairs into a JSON object.
Db*dbOpen(cchar *path, cchar *schema)
 Open a database.
intdbRemove(Db *db, cchar *model, Json *props, DbParams *params)
 Remove matching items in the database.
intdbSave(Db *db, cchar *filename)
 Save the database.
const DbItem*dbSet(Db *db, cchar *model, cchar *fieldName, cchar *value, Json *props, DbParams *params)
 Set an item field value.
const DbItem*dbSetBool(Db *db, cchar *model, cchar *fieldName, bool value, Json *props, DbParams *params)
 Set an item field value as a boolean.
const DbItem*dbSetDate(Db *db, cchar *model, cchar *fieldName, Time value, Json *props, DbParams *params)
 Set an item field value as a date.
const DbItem*dbSetDouble(Db *db, cchar *model, cchar *fieldName, double value, Json *props, DbParams *params)
 Set an item field value as a double.
const DbItem*dbSetNumber(Db *db, cchar *model, cchar *fieldName, int64 value, Json *props, DbParams *params)
 Set an item field value as a number.
voiddbSetTrigger(Db *db, DbTrigger proc, void *arg)
 Set the database change trigger callback.
const DbItem*dbUpdate(Db *db, cchar *model, Json *props, DbParams *params)
 Update an item.

Typedefs

DbGridDatabase grid of items returned from dbFind.
DbItemDatabase items stored in RB indexes.
DbModelModel schema.
DbParamsDatabase parameters.
DbTriggerDatabase trigger.

Defines

#defineDB_JSON   dbJson(str)
 Macro for supplying API properties as a JSON parsable string.
#defineDB_MAX_ITEM   (256 * 1024)
 Maximum database item length.
#defineDB_MAX_KEY   1024
 Maximum sort key length.
#defineDB_MAX_LOG_AGE   (60 * TPS)
 Maximum age of log file.
#defineDB_MAX_LOG_SIZE   (1024 * 1024)
 Maximum sort key length.
#defineDB_PARAMS   & (DbParams) { __VA_ARGS__ }
 Macro for supplying API parameters.
#defineDB_PROPS   dbJsonProps((cchar*[]) { __VA_ARGS__, NULL })
 Macro for supplying API properties as key/value pairs.
#defineDB_JSON   dbJson(str)
 Macro for supplying API properties as a JSON parsable string.
#defineDB_PARAMS   & (DbParams) { __VA_ARGS__ }
 Macro for supplying API parameters.
#defineDB_PROPS   dbJsonProps((cchar*[]) { __VA_ARGS__, NULL })
 Macro for supplying API properties as key/value pairs.

Db

Db

Embedded Database based on DynamoDB.

Description:
The DB library is a high performance NoSQL in-memory database for embedded applications modeled on DynamoDB. Data items are implemented as JSON documents and are organized into tables. Application entities are defined via an entity schema that specifies data fields and attributes. Data items are JSON documents and are accessed via a flexible API and dot notation queries. DB uses Red/black binary search indexes and has controllable persistency locally to disk and to the cloud on a per-table basis.
API Stability:
Evolving.
Fields:
intcode API error code.
Json *context Global context properties - overwrites API properties.
char *error API error message.
char *journal On-disk journal of changes.
TicksjournalCreated When journal file recreated.
REventjournalEvent Timeout for journal save.
intjournalFd Journal file descriptor.
ssizejournalSize Current size of journal file.
TicksmaxJournalAge Maximum age of journal file before saving.
ssizemaxJournalSize Maximum size of the journal before saving.
RHash *models List of schema models.
char *path On-disk path.
RbTree *primary Red/black tree primary index.
Json *schema OneTable schema.
DbTriggertrigger Database change notification trigger.
void *triggerArg Argument for the trigger callback.
cchar *type Item schema type property.

void dbAddContext (Db *db, cchar *name, cchar *value)

Add global context properties.

Description:
A global context property can be added to the set of properties supplied to each API. These property values are added at the top level only. Dotted notation is not supported.
Parameters:
dbDatabase instance.
nameName of the property.
valueProperty value to set.
API Stability:
Evolving.
See Also:

void dbClose (Db *db)

Close a database.

Description:
This will immediately save any unsaved changes and then close the database.
Parameters:
dbDatabase instance returned via dbOpen
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbCreate (Db *db, cchar *model, Json *props, DbParams *params)

Create a new item.

Description:
Create a new item of the required model type.
Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model entity to create. The model determines the valid set of properties for the created item. Set to NULL if no model is required.
propsJSON object containing the item properties to create. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
bool upsert : 1; // Update on create if present. Create on update if missing.
Returns:
The created database item. The DbItem "name" property is the indexed key value. The value "json" property contains the item values as a cached JSON object. If null, the "value" property contains the item's value as an unparsed JSON string. Caller must not free the returned item.
API Stability:
Evolving.
See Also:

cchar * dbField (const DbItem *item, cchar *fieldName)

Fetch a field value from an item as a string.

Description:
Use to examine an item returned via dbGet or other APIs that return items.
Parameters:
itemDatabase item returned from other APIs.
fieldNameName of the field to examine.
Returns:
The field value as a string. Caller must not free.
API Stability:
Evolving.
See Also:

bool dbFieldBool (const DbItem *item, cchar *fieldName)

Fetch a field value from an item as a boolean.

Description:
Use to examine an item returned via dbGet or other APIs that return items. Will return true if the item field value is set to "true" or "1".
Parameters:
itemDatabase item returned from other APIs.
fieldNameName of the field to examine.
Returns:
The field value as a boolean.
API Stability:
Evolving.
See Also:

Time dbFieldDate (const DbItem *item, cchar *fieldName)

Fetch a field value from an item as a date.

Description:
Use to examine an item returned via dbGet or other APIs that return items. This requires that the date value be stored as an ISO date string.
Parameters:
itemDatabase item returned from other APIs.
fieldNameName of the field to examine.
Returns:
The field value as a date in a Time value. This is the time in milliseconds since Jan 1 1970.
API Stability:
Evolving.
See Also:

double dbFieldDouble (const DbItem *item, cchar *fieldName)

Fetch a field value from an item as a double.

Description:
Use to examine an item returned via dbGet or other APIs that return items. This requires that the date value be stored as an ISO date string.
Parameters:
itemDatabase item returned from other APIs.
fieldNameName of the field to examine.
Returns:
The field value as a double.
API Stability:
Evolving.
See Also:

int64 dbFieldNumber (const DbItem *item, cchar *fieldName)

Fetch a field value from an item as a number (64 bit).

Description:
Use to examine an item returned via dbGet or other APIs that return items.
Parameters:
itemDatabase item returned from other APIs.
fieldNameName of the field to examine.
Returns:
The field value as a 64 bit integer.
API Stability:
Evolving.
See Also:

DbGrid * dbFind (Db *db, cchar *model, Json *props, DbParams *params)

Find matching items in the database.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for matching items. Set to NULL if no model is required.
propsJSON object containing item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
int limit; // Limit the number of returned or removed items.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
cchar *next; // Next pagination token to use as the starting point for the next page of results.
DbWhere where; // Where query expression callback function.
Returns:
A grid of matching items. The DbGrid returned contains a property "items" that is an instance of RList. Items can be enumerated or accessed using ITERATE_ITEMS, rGetNextItem and rGetItem. Caller must free the grid using dbFreeGrid.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbFindOne (Db *db, cchar *model, Json *props, DbParams *params)

Find the first matching item.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for matching items. Set to NULL if no model is required.
propsJSON object containing item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
DbWhere where; // Where query expression callback function.
Returns:
The first matching item. Returns null if no match found.
API Stability:
Evolving.
See Also:

void dbFreeGrid (DbGrid *grid)

Free a grid returned by dbFind.

Parameters:
gridGrid returned by calling dbFind
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbGet (Db *db, cchar *model, Json *props, DbParams *params)

Read a matching item from the database.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for matching items.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The matching database item. The DbItem "name" property is the indexed key. The value "json" property contains the item values as a cached JSON object. If null, the "value" property contains the item's value as an unparsed JSON string. Use dbField to access the individual field values in the item. Caller must not free the returned item.
API Stability:
Evolving.
See Also:

cchar * dbGetField (Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params)

Get a field from a matching item from the database.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for matching items.
fieldNameName of the item field to return.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
A string containing the required field in the data item.
API Stability:
Evolving.
See Also:

Json * dbJson (cchar *str)

Parse a string into Json properties.

Parameters:
strNULL terminated JSON string.
Returns:
A JSON object containing the supplied property values.
API Stability:
Internal.
See Also:

Json * dbJsonProps (cchar *props)

Convert a list of keyword / value pairs into a JSON object.

Parameters:
propsNULL terminated array of keyword / value pairs.
Returns:
A JSON object containing the supplied property values.
API Stability:
Internal.
See Also:

Db * dbOpen (cchar *path, cchar *schema)

Open a database.

Parameters:
pathFilename for from which to load and save the database when calling dbSave. On open, an initial load is performed from the file at path.
schemaOneTable data schema describing the indexes and data models.
API Stability:
Evolving.
See Also:
dbClose

int dbRemove (Db *db, cchar *model, Json *props, DbParams *params)

Remove matching items in the database.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for matching items.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify. int limit; // Limit the number of items to remove.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
A count of the number of items removed.
API Stability:
Evolving.
See Also:

int dbSave (Db *db, cchar *filename)

Save the database.

Parameters:
dbDatabase instance.
filenameOptional filename to save data to. If set to NULL, the data is saved to the name given when opening the database via dbOpen
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbSet (Db *db, cchar *model, cchar *fieldName, cchar *value, Json *props, DbParams *params)

Set an item field value.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
fieldNameName of the item field to set.
valueValue to assign to the item's field.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbSetBool (Db *db, cchar *model, cchar *fieldName, bool value, Json *props, DbParams *params)

Set an item field value as a boolean.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
fieldNameName of the item field to set.
valueValue to assign to the item's field.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbSetDate (Db *db, cchar *model, cchar *fieldName, Time value, Json *props, DbParams *params)

Set an item field value as a date.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
fieldNameName of the item field to set.
valueValue to assign to the item's field.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbSetDouble (Db *db, cchar *model, cchar *fieldName, double value, Json *props, DbParams *params)

Set an item field value as a double.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
fieldNameName of the item field to set.
valueValue to assign to the item's field.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbSetNumber (Db *db, cchar *model, cchar *fieldName, int64 value, Json *props, DbParams *params)

Set an item field value as a number.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
fieldNameName of the item field to set.
valueValue to assign to the item's field.
propsJSON object containing the item properties to match. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

void dbSetTrigger (Db *db, DbTrigger proc, void *arg)

Set the database change trigger callback.

Description:
When database items are changed, the trigger callback is invoked to notify regarding the change.
Parameters:
dbDatabase instance.
procDatabase trigger function.
argArgument to pass to the trigger function.
API Stability:
Evolving.
See Also:

const DbItem * DbItem* dbUpdate (Db *db, cchar *model, Json *props, DbParams *params)

Update an item.

Parameters:
dbDatabase instance returned via dbOpen
modelName of the schema model for the item. Set to NULL if no model is required.
propsJSON object containing the item properties to update. Use the macro DB_PROP(name, value, ...) to specify the properties as a list of keyword / value pairs. Use DB_JSON to provide the properties as a JSON/5 string. For example: DB_PROP("name", name, "address", "12 Wishbury lane") or DB_JSON("{role: 'user'}"). If a model is provided, the properties are validated against the model and unknown property names will not be written to the database.
paramsList of API parameters. Use the macro DB_PARAMS(key = value, ...) to specify.
cchar *index; // Name of the index to use. Defaults to "primary". Currently only supports "primary".
Returns:
The updated item. Caller must not free.
API Stability:
Evolving.
See Also:

Typedefs

typedef RList DbGrid.

Database grid of items returned from dbFind.

API Stability:
Evolving.
See Also:

typedef void(* DbTrigger) (void *arg, struct Db *db, struct DbModel *model, struct DbItem *item, struct DbParams *params, cchar *cmd).

Database trigger.

Parameters:
argUser argument provided to dbSetTrigger.
dbDatabase instance.
modelDbModel reference describing the item's schema model.
itemDatabase item that is changing.
paramsUser params provided to the API that caused the change.
cmdThe nature of the change. Set to "create", "update" or "remove".
API Stability:
Evolving.
See Also:

DbItem

Database items stored in RB indexes.

API Stability:
Evolving.
Fields:
uintallocatedName The name is allocated and must be freed when removed.
uintallocatedValue The value is allocated and must be freed when removed.
Json *json Parsed JSON value of the item.
char *key Indexed name of the item. Used as the sort key.
char *value Text value of the item (JSON string).

DbModel

Model schema.

Description:
The model schema defines an application entity and the supported entity fields.
Fields:
RHash *fields Hash of model fields.
cchar *name Name of the model.
uintsync Sync model items to the cloud.
API Stability:
Evolving.

DbParams

Database parameters.

API Stability:
Evolving.
Fields:
cchar *index Name of index to use. Defaults to "primary". Currently only supports "primary".
intlimit Limit the number of returned or removed items.
boollog Emit trace information to the log.
cchar *next Next pagination token to use as the starting point for the next page of results.
boolupsert Update on create if present. Create on update if missing.
DbWherewhere Where query expression callback.