Database store

⭐ New in 0.2.9.

Database store offers simple API for saving and loading key/value pairs from permanent storage. Database can be either globally available to all Detroit applications which is located in system database directory (usually /var/db/), or it can be local one located in user home directory. Database supports AES encryption.

Database system uses Berkeley DB as its backend, and when engine is compiled, it looks dbd include files from directory named db, like /usr/include/db or /usr/local/include/db. On some systems (like in my FreeBSD), that directory is named db18 (at the time of writing). In order to include database support to Detroit engine, you would need to make symlink named db pointing to db18 directory, for example like below, or use some other mechanism to provide that directory to build system:

# cd /usr/local/include
# ln -s db18 db

You may want to remove that symlink when it is no longer needed, so it does not mess with package management tools.

Functions

Each database store function explained.

store_open

Create new database or open existing one.

Returns database handle on success, zero on failure.

handle
store_open([int] scope, [int] db_type, [int] file_mode, [string] password)

scope tells database location, which can be one of:

STORE_SCOPE_LOCAL is located in user home directory, and
STORE_SCOPE_GLOBAL is located in system database directory, whichever it may be. Directory is looked from /usr/include/paths.h in _PATH_VARDB constant, and if not found, /var/db/ is used.

db_type tells database type, which can be one of:

STORE_TYPE_BTREE makes btree database, and
STORE_TYPE_HASH makes hashed database.

file_mode creates datbase file with file_mode which modified by the process umask value, zero is good default.
password makes AES encrypted database if password is given. This same password is needed when encrypted database is opened again.

store_close

Close and sync database. Store functions are not useable after this functions returns.

void
store_close([handle] store_handle)

store_handle is the handle returned by store_open().

store_remove

Remove existing database. Database must not be open when removing it. Call store_close() before calling this if database is open.

Returns zero on success, non-zero on failure.

int
store_remove([int] scope, [string] password)

scope tells database location, which can be one of:

STORE_SCOPE_LOCAL is located in user home directory, and
STORE_SCOPE_GLOBAL is located in system database directory, whichever it may be. Directory is looked from /usr/include/paths.h in _PATH_VARDB constant, and if not found, /var/db/ is used.

password is the password that were given when database was created, if any.

store_truncate

Truncate database.

Returns zero on failure (no deleted records), or non-zero value telling how many records was deleted.

u32
store_truncate([handle] store_handle)

store_handle is the handle returned by store_open().

store_sync

Sync database to permanent storage.

Returns zero on success, non-zero on failure.

int
store_sync([handle] store_handle)

store_handle is the handle returned by store_open().

store_get

Get data by key from database.

Returns zero on success, -1 on failure, or other non-zero value if key was not found in database.

int
store_get([handle] store_handle, [string] key, [pointer] data, [usize] data_size)

store_handle is the handle returned by store_open().
key is the name of data key to get.
data is the pointer to data buffer, this can be tied pointer/variable pair, see pointer for more info.
data_size is the size of the data buffer in bytes, if zero, buffer large enough is allocated and must be freed by store_get_free().

store_get_free

Free buffer returned by store_get().

void
store_get_free([pointer] data)

data is the pointer returned by store_get().

store_put

Put data to database.

Returns zero on success, non-zero on failure.

int
store_put([handle] store_handle, [string] key, [string] data, [usize] data_size)

store_handle is the handle returned by store_open().
key is the name of the key to create for data.
data is the pointer to data buffer, this can be tied pointer/variable pair, see pointer for more info.
data_size is the size of the data buffer in bytes.

store_del

Delete key/value pair from database.

Returns zero on success, -1 on failure, or other non-zero value if key was not found from database.

int
store_del([handle] store_handle, [string] key)

store_handle is the handle returned by store_open().
key is the name of the key to delete.

store_exists

Check if key exists in database.

Returns zero on success (the key exists), -1 on failure, or other non-zero value if key was not found from database.

int
store_exists([handle] store_handle, [string] key)

store_handle is the handle returned by store_open().
key is the name of the key to check.