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.

Function Index

void	dbAddCallback(Db db, DbCallbackProc proc, cchar model, void *arg, int events)
	Add a database change trigger callback.
void	dbAddContext(Db db, cchar name, cchar *value)
	Add global context properties.
void	dbClose(Db *db)
	Close a database.
void	dbCompact(Db *db)
	Compact database storage.
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.
bool	dbFieldBool(const DbItem item, cchar fieldName)
	Fetch a field value from an item as a boolean.
Time	dbFieldDate(const DbItem item, cchar fieldName)
	Fetch a field value from an item as a date.
double	dbFieldDouble(const DbItem item, cchar fieldName)
	Fetch a field value from an item as a double.
int64	dbFieldNumber(const DbItem item, cchar fieldName)
	Fetch a field value from an item as a number (64 bit).
RList *	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.
const DbItem *	dbGet(Db db, cchar model, Json props, DbParams params)
	Read a matching item from the database.
bool	dbGetBool(Db db, cchar model, cchar fieldName, Json props, DbParams *params, bool defaultValue)
	Get a field value from an item as a boolean.
Time	dbGetDate(Db db, cchar model, cchar fieldName, Json props, DbParams *params, Time defaultValue)
	Get a field value from an item as a date.
double	dbGetDouble(Db db, cchar model, cchar fieldName, Json props, DbParams *params, double defaultValue)
	Get a field value from an item as a double.
cchar *	dbGetError(Db *db)
	Get an error message for the most recent API call.
cchar *	dbGetField(Db db, cchar model, cchar fieldName, Json props, DbParams *params)
	Get a field from a matching item from the database.
DbModel *	dbGetItemModel(Db db, CDbItem item)
	Get the model object for a data item.
DbModel *	dbGetModel(Db db, cchar name)
	Get the model object for a model name.
int64	dbGetNum(Db db, cchar model, cchar fieldName, Json props, DbParams *params, int64 defaultValue)
	Get a field value from an item as a number.
cchar *	dbGetSortKey(Db *db)
	Get the primary sort key field name.
char *	dbGetUID(ssize size)
	Generate a unique identifier of specified length.
char *	dbGetULID(Time when)
	Generate a Universally Unique Lexicographically Sortable Identifier (ULID).
const Json *	dbJson(const DbItem *item)
	Get JSON object representing a database item.
char *	dbListToString(RList *list)
	Convert item list to JSON string representation.
int	dbLoadData(Db db, cchar path)
	Load data from JSON file into database.
int	dbLoadDataItems(Db db, Json json, JsonNode *parent)
	Load data from JSON object into database.
cchar *	dbNext(Db db, RList list)
	Get the next key when using paginated find requests.
Db *	dbOpen(cchar path, cchar schema, int flags)
	Open a database.
void	dbPrint(Db *db)
	Print all database items to stdout.
void	dbPrintItem(const DbItem *item)
	Print database item to stdout.
void	dbPrintProperties(Json *properties)
	Print JSON properties to stdout.
Json *	dbPropsToJson(cchar *props[])
	Convert a list of keyword / value pairs into a JSON object.
int	dbRemove(Db db, cchar model, Json props, DbParams params)
	Remove matching items in the database.
void	dbRemoveCallback(Db db, DbCallbackProc proc, cchar model, void *arg)
	Remove a database change trigger callback.
int	dbRemoveExpired(Db *db, bool notify)
	Remove expired database items.
int	dbSave(Db db, cchar filename)
	Save the database.
const DbItem *	dbSetBool(Db db, cchar model, cchar fieldName, bool value, Json props, DbParams *params)
	Update a database item field value as a boolean.
const DbItem *	dbSetDate(Db db, cchar model, cchar fieldName, Time value, Json props, DbParams *params)
	Update a database item field value as a date.
const DbItem *	dbSetDouble(Db db, cchar model, cchar fieldName, double value, Json props, DbParams *params)
	Update a database item field value as a double.
const DbItem *	dbSetField(Db db, cchar model, cchar fieldName, cchar value, Json props, DbParams params)
	Update a database item field value.
void	dbSetJournalParams(Db *db, Ticks delay, ssize size)
	Configure database journaling parameters.
const DbItem *	dbSetNum(Db db, cchar model, cchar fieldName, int64 value, Json props, DbParams *params)
	Update a database item field value as a number.
const DbItem *	dbSetString(Db db, cchar model, cchar fieldName, cchar value, Json props, DbParams params)
	Update a database item field value as a string.
cchar *	dbString(const DbItem *item, int flags)
	Convert database item to JSON string.
Json *	dbStringToJson(cchar *fmt, ...)
	Parse a string into Json properties.
cchar *	dbType(Db *db)
	Get the type field of database items.
const DbItem *	dbUpdate(Db db, cchar model, Json props, DbParams params)
	Update an item.

Typedef Index

Db	Main database instance structure.
DbCallbackProc	Database change notification callback.
DbItem	Database items stored in RB indexes.
DbModel	Database model schema definition.
DbParams	Database parameters.

Defines

#define	DB_INMEM -2
	Don't persist change to storage - preserve in memory only.
#define	DB_JSON dbStringToJson(__VA_ARGS__)
	Macro for supplying API properties as a string in JSON format.
#define	DB_MAX_ITEM (256 * 1024)
	Maximum database item length.
#define	DB_MAX_KEY 1024
	Maximum sort key length.
#define	DB_MAX_LOG_AGE (60 * TPS)
	Maximum age of log file.
#define	DB_MAX_LOG_SIZE (1024 * 1024)
	Maximum journal size.
#define	DB_NODELAY -1
	Don't delay, persist immediately.
#define	DB_OPEN_RESET 0x2
	Reset (erase) database on open.
#define	DB_PARAMS ((DbParams[]){ { __VA_ARGS__ } })
	Macro for supplying API parameters.
#define	DB_PROPS dbPropsToJson((cchar*[]) { __VA_ARGS__, NULL })
	Macro for supplying API properties as key/value pairs.
#define	DB_READ_ONLY 0x1
	Database flags.

Typedefs

typedef void(* DbCallbackProc) (void *arg, struct Db *db, struct DbModel *model, struct DbItem *item, struct DbParams *params, cchar *cmd, int events)

Database change notification callback.

Description:: Called when database items are modified, allowing applications to respond to data changes. Callbacks can be registered for specific events and models to enable features like cloud synchronization, audit logging, or cache invalidation.

Parameters:

arg	User-defined argument provided when registering the callback.
db	Database instance where the change occurred.
model	Schema model describing the item's structure and validation rules.
item	Database item that was modified.
params	API parameters used in the operation that triggered the change.
cmd	Type of change operation: "create", "update", or "remove".
events	Event types that triggered this callback: DB_ON_CHANGE, DB_ON_COMMIT, or both.

API Stability:: Evolving.

Main database instance structure.

Description:: High-performance NoSQL embedded database inspired by DynamoDB design principles. Stores JSON documents with schema-based validation and efficient red/black tree indexing. Provides transaction journaling for crash recovery, configurable persistence policies, and optional cloud synchronization capabilities. Designed for embedded applications requiring fast local data access with minimal memory footprint.

Fields:

RList *	callbacks	Database change notification triggers.
RHash *	changes	Hash of pending changes.
int	code	API error code.
REvent	commitEvent	Timeout for commit event.
Json *	context	Global context properties applied to all API operations.
Ticks	due	When delayed commits are due.
char *	error	API error message.
int	flags	Database configuration flags (reserved for future use).
FILE *	journal	Journal file descriptor.
Ticks	journalCreated	When journal file recreated.
bool	journalError	Journal I/O error.
REvent	journalEvent	Timeout for journal save.
char *	journalPath	On-disk journal filename.
ssize	journalSize	Current size of journal file.
Ticks	maxJournalAge	Maximum age of journal file before saving.
ssize	maxJournalSize	Maximum size of the journal before saving.
RHash *	models	List of schema models.
bool	needSave	Database needs saving.
char *	path	On-disk path.
RbTree *	primary	Red/black tree primary index.
Json *	schema	Database schema defining models, fields, and validation rules.
bool	servicing	Servicing database.
bool	timestamps	Maintain created/updated timestamps (if in schema).
cchar *	type	Name of the field used to identify item types in the schema.

API Stability:: Evolving.

DbItem

Database items stored in RB indexes.

API Stability:: Evolving.

Fields:

uint	allocatedName	The name is allocated and must be freed when removed.
uint	allocatedValue	The value is allocated and must be freed when removed.
uint	delayed	Update to journal and cloud delayed.
Json *	json	Parsed JSON value of the item, takes precedence over value.
char *	key	Indexed name of the item. Used as the sort key.
char *	value	Text value of the item (JSON string), may be stale if json set.

DbModel

Database model schema definition.

Description:: Defines an application entity type with its supported fields, validation rules, and behavior. Models provide schema validation, field type checking, and control persistence and synchronization policies for groups of related items.

Fields:

Time	delay	Time to delay before committing changes.
cchar *	expiresField	Name of the TTL field.
RHash *	fields	Hash of model fields.
uint	mem	Keep model in-memory and not persisted to storage.
cchar *	name	Name of the model.
uint	sync	Sync model items to the cloud.

API Stability:: Evolving.

DbParams

Database parameters.

API Stability:: Evolving.

Fields:

cvoid *	arg	Argument to where callback.
bool	bypass	Bypass changes.
int	delay	Delay before commmiting changes (Delay in msec, -1 == nocommit).
cchar *	index	Index name. Default to "primary". Currently only supports "primary".
int	limit	Limit the number of returned or removed items.
bool	log	Emit trace information to the log.
bool	mem	Update in memory only.
cchar *	next	Pagination token starting point for the next page of results.
bool	upsert	Update on create if present. Create on update if missing.
DbWhere	where	Where query expression callback.

Functions

void dbAddCallback (Db *db, DbCallbackProc proc, cchar *model, void *arg, int events)

Add a database change trigger callback.

Description:: When database items are changed, the trigger callbacks are invoked to notify regarding the change.

Parameters:

db	Database instance.
proc	Database trigger function.
model	Target model. If null, then match all models.
arg	Argument to pass to the trigger function.
events	Events of interest. Set to DB_ON_CHANGE, DB_ON_COMMIT (or both).

API Stability:: Evolving.

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:

db	Database instance.
name	Name of the property.
value	Property value to set.

API Stability:: Evolving.

void dbClose (Db *db)

Close a database.

Description:: This will immediately save any unsaved changes and then close the database.

Parameters:

db	Database instance returned via dbOpen.

API Stability:: Evolving.

void dbCompact (Db *db)

Compact database storage.

Description:: Optimizes database storage by converting parsed JSON items back to compact string representations. This reduces memory usage and improves storage efficiency by eliminating redundant parsed JSON structures while preserving all data.

Parameters:

db	Database instance returned from dbOpen.

API Stability:: Evolving.

const 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:

db	Database instance returned via dbOpen.
model	Name 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.
props	JSON 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.
params	List 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. Caller must not free the returned item. Returns null on errors. Use dbGetError to retrieve an error message.

API Stability:: Evolving.

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.

: : WARNING: This function returns a pointer to a string that is part of the DbItem structure. Subsequent updates to the item will invalidate the pointer.

Parameters:

item	Database item returned from other APIs.
fieldName	Name of the field to examine.

Returns:: The field value as a string. Caller must not free.

API Stability:: Evolving.

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:

item	Database item returned from other APIs.
fieldName	Name of the field to examine.

Returns:: The field value as a boolean.

API Stability:: Evolving.

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:

item	Database item returned from other APIs.
fieldName	Name 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.

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. Converts numeric field values to double precision floating point format.

Parameters:

item	Database item returned from other APIs.
fieldName	Name of the field to examine.

Returns:: The field value as a double.

API Stability:: Evolving.

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:

item	Database item returned from other APIs.
fieldName	Name of the field to examine.

Returns:: The field value as a 64 bit integer.

API Stability:: Evolving.

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

Find matching items in the database.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items. Set to NULL if no model is required.
props	JSON 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.
params	List 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 list of matching items. Items can be enumerated or accessed using ITERATE_ITEMS, rGetNextItem and rGetItem. Caller must free the result using rFreeList.

API Stability:: Evolving.

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

Find the first matching item.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items. Set to NULL if no model is required.
props	JSON 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.
params	List 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.

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

Read a matching item from the database.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
props	JSON 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.
params	List 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.

bool dbGetBool (Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params, bool defaultValue)

Get a field value from an item as a boolean.

Description:: If the field is not found, the default value is returned. Use dbGetField if you must know if the field is missing.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
fieldName	Name of the item field to return.
props	JSON 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.
params	List 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".
defaultValue	Default value to return if the field is not found.

Returns:: The field value as a boolean.

API Stability:: Evolving.

Time dbGetDate (Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params, Time defaultValue)

Get a field value from an item as a date.

Description:: If the field is not found, the default value is returned. Use dbGetField if you must know if the field is missing.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
fieldName	Name of the item field to return.
props	JSON 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.
params	List 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".
defaultValue	Default value to return if the field is not found.

Returns:: The field value as a date of seconds since epoch (Jan 1 1970).

API Stability:: Evolving.

double dbGetDouble (Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params, double defaultValue)

Get a field value from an item as a double.

Description:: If the field is not found, the default value is returned. Use dbGetField if you must know if the field is missing.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
fieldName	Name of the item field to return.
props	JSON 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.
params	List 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".
defaultValue	Default value to return if the field is not found.

Returns:: The field value as a double.

API Stability:: Evolving.

cchar * dbGetError (Db *db)

Get an error message for the most recent API call.

Parameters:

db	Database instance returned via dbOpen.

Returns:: A static error message string. Caller must not free.

API Stability:: Evolving.

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

Get a field from a matching item from the database.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
fieldName	Name of the item field to return.
props	JSON 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.
params	List 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. Caller must not free.

API Stability:: Evolving.

DbModel * dbGetItemModel (Db *db, CDbItem *item)

Get the model object for a data item.

Parameters:

db	Database instance.
item	Data item with a model type field.

Returns:: A model instance.

API Stability:: Evolving.

DbModel * dbGetModel (Db *db, cchar *name)

Get the model object for a model name.

Parameters:

db	Database instance.
name	Model name.

Returns:: A model instance.

API Stability:: Evolving.

int64 dbGetNum (Db *db, cchar *model, cchar *fieldName, Json *props, DbParams *params, int64 defaultValue)

Get a field value from an item as a number.

Description:: If the field is not found, the default value is returned. Use dbGetField if you must know if the field is missing.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
fieldName	Name of the item field to return.
props	JSON 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.
params	List 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".
defaultValue	Default value to return if the field is not found.

Returns:: The field value as a number.

API Stability:: Evolving.

cchar * dbGetSortKey (Db *db)

Get the primary sort key field name.

Description:: Returns the name of the field used as the primary sort key for database items. This field determines the ordering of items in the primary index.

Parameters:

db	Database instance returned from dbOpen.

Returns:: Name of the sort key field. Caller must not free.

API Stability:: Evolving.

char * dbGetUID (ssize size)

Generate a unique identifier of specified length.

Description:: Creates a random unique identifier string of the requested size. Uses cryptographically secure random number generation.

Parameters:

size	Length of the generated UID string.

Returns:: Newly allocated UID string. Caller must free with rFree.

API Stability:: Evolving.

char * dbGetULID (Time when)

Generate a Universally Unique Lexicographically Sortable Identifier (ULID).

Description:: Creates a ULID based on the specified timestamp. ULIDs are 26-character case-insensitive strings that encode both timestamp and randomness, providing sortable unique identifiers.

Parameters:

when	Timestamp to embed in the ULID (milliseconds since epoch).

Returns:: Newly allocated ULID string. Caller must free with rFree.

API Stability:: Evolving.

const Json * dbJson (const DbItem *item)

Get JSON object representing a database item.

Description:: Retrieve the parsed JSON representation of a database item. The returned JSON object provides access to all item fields and values.

Parameters:

item	Database item returned from dbCreate, dbGet, dbFind or dbUpdate.

Returns:: JSON object containing item data. This is an internal reference - caller must NOT modify or free. Returns NULL if item is invalid.

API Stability:: Evolving.

char * dbListToString (RList *list)

Convert item list to JSON string representation.

Description:: Serializes a list of database items into a JSON string format. Useful for exporting query results or transmitting data.

Parameters:

list	List of DbItem objects returned from dbFind.

Returns:: Newly allocated JSON string containing the serialized items. Caller must free with rFree. Returns NULL if list is empty or invalid.

API Stability:: Evolving.

int dbLoadData (Db *db, cchar *path)

Load data from JSON file into database.

Description:: Loads JSON data from a file into the database. Existing items with matching keys will be overwritten. This operation is useful for loading initial state data, test fixtures, or restoring database content from backups.

Parameters:

db	Database instance returned from dbOpen.
path	Path to JSON data file to load.

Returns:: Zero on success, negative error code on failure.

API Stability:: Evolving.

int dbLoadDataItems (Db *db, Json *json, JsonNode *parent)

Load data from JSON object into database.

Description:: Loads JSON data from a parsed JSON object into the database. Existing items with matching keys will be overwritten. This operation processes data items from the specified parent node in the JSON structure.

Parameters:

db	Database instance returned from dbOpen.
json	Parsed JSON object containing data to load.
parent	Parent JSON node containing the data items to load.

Returns:: Zero on success, negative error code on failure.

API Stability:: Evolving.

cchar * dbNext (Db *db, RList *list)

Get the next key when using paginated find requests.

Parameters:

db	Database instance.
list	A list returned from a prior dbFind request.

Returns:: A reference into the last item returned in the list.

API Stability:: Evolving.

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

Open a database.

Parameters:

path	Filename for from which to load and save the database when calling dbSave. On open, an initial load is performed from the file at path.
schema	OneTable data schema describing the indexes and data models.
flags	Reserved. Set to zero.

API Stability:: Evolving.

void dbPrint (Db *db)

Print all database items to stdout.

Description:: Outputs a formatted representation of all items in the database to standard output. Useful for debugging and examining database contents during development.

Parameters:

db	Database instance returned from dbOpen.

API Stability:: Evolving.

void dbPrintItem (const DbItem *item)

Print database item to stdout.

Description:: Outputs a formatted representation of a database item to standard output. Useful for debugging and development.

Parameters:

item	Database item returned from dbCreate, dbGet, dbFind or dbUpdate.

API Stability:: Evolving.

void dbPrintProperties (Json *properties)

Print JSON properties to stdout.

Description:: Outputs a formatted representation of JSON properties to standard output. Useful for debugging and examining property values during development.

Parameters:

properties

JSON object containing properties to display.

API Stability:: Evolving.

Json * dbPropsToJson (cchar *props)

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

Parameters:

props

NULL terminated array of keyword / value pairs.

Returns:: A JSON object containing the supplied property values.

API Stability:: Internal.

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

Remove matching items in the database.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for matching items.
props	JSON 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.
params	List 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.

void dbRemoveCallback (Db *db, DbCallbackProc proc, cchar *model, void *arg)

Remove a database change trigger callback.

Parameters:

db	Database instance.
proc	Database trigger function.
model	Target model. If null, then match all models.
arg	Argument to pass to the trigger function.

API Stability:: Evolving.

int dbRemoveExpired (Db *db, bool notify)

Remove expired database items.

Description:: Removes items from the database that have exceeded their TTL (time-to-live) expiration. Items are considered expired when their TTL field value is less than the current time. This operation helps maintain database efficiency by automatically cleaning up stale data.

Parameters:

db	Database instance returned from dbOpen.
notify	Set to true to invoke registered callback notifiers for each removed item.

Returns:: Number of items removed, or negative error code on failure.

API Stability:: Prototype.

int dbSave (Db *db, cchar *filename)

Save the database.

Parameters:

db	Database instance.
filename	Optional 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.

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

Update a database item field value as a boolean.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

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

Update a database item field value as a date.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

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

Update a database item field value as a double.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

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

Update a database item field value.

Description:: Update a field in an existing item. The item must already exist. This sets the field value to the string value.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

void dbSetJournalParams (Db *db, Ticks delay, ssize size)

Configure database journaling parameters.

Description:: Sets the journaling behavior for database persistence. The journal records changes before they are written to the main database file, providing crash recovery capability. Changes are automatically committed when either the delay time expires or the journal reaches the maximum size limit.

Parameters:

db	Database instance returned from dbOpen.
delay	Maximum time in milliseconds to delay before committing journal changes to the persistent database file.
size	Maximum journal file size in bytes before flushing to the persistent database file.

API Stability:: Evolving.

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

Update a database item field value as a number.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

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

Update a database item field value as a string.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
fieldName	Name of the item field to set.
value	Value to assign to the item's field.
props	JSON 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.
params	List 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.

cchar * dbString (const DbItem *item, int flags)

Convert database item to JSON string.

Description:: Serializes a database item into a JSON string with specified formatting options.

Parameters:

item	Database item returned from dbCreate, dbGet, dbFind or dbUpdate.
flags	Formatting options: JSON_HUMAN (pretty-printed), JSON_JSON (strict JSON), JSON_JSON5 (JSON5 format), or other jsonToString flags.

Returns:: JSON string representation. This is an internal reference - caller must not free. Returns NULL if item is invalid.

API Stability:: Evolving.

Json * dbStringToJson (cchar *fmt, ...)

Parse a string into Json properties.

Parameters:

fmt	Printf style format string.
...	Arguments to fmt.

Returns:: A JSON object containing the supplied property values.

API Stability:: Internal.

cchar * dbType (Db *db)

Get the type field of database items.

Parameters:

db	Database instance returned via dbOpen.

Returns:: The type field used by database items. Caller must not free.

API Stability:: Evolving.

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

Update an item.

Parameters:

db	Database instance returned via dbOpen.
model	Name of the schema model for the item. Set to NULL if no model is required.
props	JSON 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.
params	List 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. Returns null on errors. Use dbGetError to retrieve an error message.

API Stability:: Evolving.

Files

AI

Database

URL HTTP Client

Safe Runtime

Web Server

Configuration

Man Pages

DB API

Function Index

Typedef Index

Defines

Typedefs

Functions

Configuration

DB API ​

Function Index ​

Typedef Index ​

Defines ​

Typedefs ​

Functions ​

DB API

Function Index

Typedef Index

Defines

Typedefs

Functions