Reference/Databases

Databases

CDatabase

Local persistent databases and typed, indexed row tables.

C++23 mc/CDatabase.h
#include <mc/CDatabase.h>

Keep the CDatabase alive longer than its table handles. Cosmic database schemas generate row types used by CTable<R>; clients keep the same schema and query syntax.

Table writes are staged until commit(). rollback() discards staged changes. A commit updates the table; background persistence is controlled separately by setSaveInterval().

Row ID zero is invalid. Updating a row can assign a new ID. Several row operations are declared noexcept; callbacks and argument conversions must honor that contract.

Jump to a declaration · 43
cquery CDatabase CDatabase::CDatabase CDatabase::compact CDatabase::createTable CDatabase::eraseTable CDatabase::exists CDatabase::getTable CDatabase::renameTable CDatabase::setErrorStream CDatabase::setMemoryLimit CDatabase::setSaveInterval CDatabase::shutdown_ CDatabase::~CDatabase CTable CTable::commit CTable::count CTable::dump CTable::erase CTable::get CTable::getMax CTable::getMin CTable::getRows CTable::has CTable::insert CTable::query CTable::QueryFunc CTable::QueryFunc_ CTable::reserve CTable::rollback CTable::RowId CTable::RowSet CTable::RowType CTable::RowVector CTable::setQuery CTable::toHashMap CTable::toMap CTable::toMultimap CTable::traverseBackward CTable::traverseForward CTable::update CTable::UpdateMap_ CTable::vectorQuery

CTable

template<CCRow R> class CTable

Types, constants & data

using RowType = R;
using RowId = typename R::RowId;
using RowSet = CHashSet<RowId>;
using RowVector = CVector<RowId>;
using QueryFunc_ = std::function<bool(RowId rowId, cvec& r)>;
using UpdateMap_ = CHashMap<RowId, RowId>;
using QueryFunc = std::function<bool(R& r)>;

Methods

dump

void dump();

Writes diagnostic table contents to the implementation’s output stream. This is an inspection aid rather than an export format.

reserve

void reserve(size_t numRows);

Reserves space for the specified number of staged rows on this table handle. It does not insert rows or preallocate persistent row IDs.

insert

void insert(R& row) noexcept;
void insert(R&& row) noexcept;

Stages a row for insertion; it becomes committed through commit(). The lvalue overload copies the row, while the rvalue overload may consume its fields.

erase

void erase(RowId rowId) noexcept;
void erase(R& row) noexcept;

Stages deletion of a row by its persistent ID or row object. Call commit() to publish the deletion, or rollback() to discard it.

update

void update(R& row);
void update(R&& row);

Stages replacement of a row that already has a nonzero row ID. Commit can assign a new physical row ID; callers must not assume the replacement retains the original ID.

commit

void commit();

Applies staged row and index changes; commit validation can fail, for example on a unique-key conflict.

rollback

void rollback() noexcept;

Discards staged changes.

get

bool get(const CFields& fs, R& row, RowId rowId) noexcept;
bool get(R& row, RowId rowId) noexcept;
void get(const CFields& fs, const RowSet& rs, QueryFunc qf) noexcept;
void get(const RowSet& rs, QueryFunc qf) noexcept;
void get(const CFields& fs, const RowVector& rs, QueryFunc qf) noexcept;
void get(const RowVector& rs, QueryFunc qf) noexcept;
template<CCField F> bool get(const CFields& fs, R& row, typename CTableFieldValueType_<F>::type value) noexcept;
template<CCField F> bool get(R& row, typename CTableFieldValueType_<F>::type value) noexcept;
template<class FS, class... Args> requires(CIsTuple<FS>) bool get(const CFields& fs, R& row, typename std::tuple_element<0, FS>::type::type value, Args&&... args) noexcept;
template<class FS, class... Args> requires(CIsTuple<FS>) bool get(R& row, typename std::tuple_element<0, FS>::type::type value, Args&&... args) noexcept;

Fetches rows by ID or index. Boolean overloads report whether a row was found; callbacks return false to stop.

has

template<CCField F> bool has(typename CTableFieldValueType_<F>::type value) noexcept;
template<class FS, class... Args> requires(CIsTuple<FS>) bool has(typename CTableFieldValueType_<typename std::tuple_element<0, FS>::type>::type value, Args&&... args) noexcept;

Tests whether an indexed value exists in committed table data. Composite-index overloads also constrain the remaining key fields.

query

template<CCField F> void query(const CFields& fs, QueryFunc func, typename F::type start, typename F::type end);
template<CCField F> void query(QueryFunc func, typename F::type start, typename F::type end);
template<CCField F> void query(const CFields& fs, QueryFunc func, typename F::type value);
template<CCField F> void query(QueryFunc func, typename F::type value);
template<class FS, class... Args> requires(CIsTuple<FS>) void query(const CFields& fs, QueryFunc func, typename std::tuple_element<0, FS>::type::type start, typename std::tuple_element<0, FS>::type::type end, Args&&... args);
template<class FS, class... Args> requires(CIsTuple<FS>) void query(QueryFunc func, typename std::tuple_element<0, FS>::type::type start, typename std::tuple_element<0, FS>::type::type end, Args&&... args);

Applies an indexed query to a row-ID set.

getRows

template<CCField F> void getRows(const CFields& fs, CVector<R>& rows, typename F::type value);
template<CCField F> void getRows(CVector<R>& rows, typename F::type value);
template<class FS, class... Args> requires(CIsTuple<FS>) void getRows(const CFields& fs, CVector<R>& rows, typename std::tuple_element<0, FS>::type::type value, Args&&... args);
template<class FS, class... Args> requires(CIsTuple<FS>) void getRows(CVector<R>& rows, typename std::tuple_element<0, FS>::type::type value, Args&&... args);

Appends matching rows to the supplied output vector without clearing it. A field selection limits which fields are materialized.

setQuery

template<CCField F> void setQuery(RowSet& rs, typename F::type start, typename F::type end);
template<CCField F> void setQuery(RowSet& rs, typename F::type value);
template<class FS, class TV, class... Args> requires(CIsTuple<FS>) void setQuery(RowSet& rs, typename std::tuple_element<0, FS>::type::type start, typename std::tuple_element<0, FS>::type::type end, Args&&... args);

Adds matching row IDs to the supplied set, preserving existing members and suppressing duplicate IDs. Use get() afterwards when row contents are needed.

vectorQuery

template<CCField F> void vectorQuery(RowVector& rs, typename F::type start, typename F::type end);
template<CCField F> void vectorQuery(RowVector& rs, typename F::type value);
template<class FS, class TV, class... Args> requires(CIsTuple<FS>) void vectorQuery(RowVector& rs, typename std::tuple_element<0, FS>::type::type start, typename std::tuple_element<0, FS>::type::type end, Args&&... args);

Appends matching row IDs to the supplied vector without clearing it. A separate get() can retrieve selected fields for those IDs.

traverseForward

template<CCField F> void traverseForward(const CFields& fs, QueryFunc func);
template<CCField F> void traverseForward(QueryFunc func);
template<class FS, class... Args> requires(CIsTuple<FS>) void traverseForward(const CFields& fs, QueryFunc func, Args&&... args);
template<class FS, class... Args> requires(CIsTuple<FS>) void traverseForward(QueryFunc func, Args&&... args);
void traverseForward(const CFields& fs, QueryFunc func);
void traverseForward(QueryFunc func);

Visits rows in forward index order; false from the callback stops traversal.

traverseBackward

template<CCField F> void traverseBackward(const CFields& fs, QueryFunc func);
template<CCField F> void traverseBackward(QueryFunc func);
template<class FS, class... Args> requires(CIsTuple<FS>) void traverseBackward(const CFields& fs, QueryFunc func, Args&&... args);
template<class FS, class... Args> requires(CIsTuple<FS>) void traverseBackward(QueryFunc func, Args&&... args);
void traverseBackward(const CFields& fs, QueryFunc func);
void traverseBackward(QueryFunc func);

Visits rows in reverse index order; false from the callback stops traversal.

getMin

template<class FS, class... Args> bool getMin(R& ret, Args&&... args);
template<class FS, class... Args> bool getMin(const CFields& fs, R& ret, Args&&... args);

Retrieves the first matching row in forward index order.

getMax

template<class FS, class... Args> bool getMax(R& ret, Args&&... args);
template<class FS, class... Args> bool getMax(const CFields& fs, R& ret, Args&&... args);

Retrieves the first matching row in reverse index order.

toMap

template<class K, class V> auto toMap();

Builds an ordered map from the selected key and value fields. Duplicate keys retain the first value encountered during forward traversal.

toHashMap

template<class K, class V> auto toHashMap();

Builds a hash map from the selected key and value fields. Duplicate keys retain the first value encountered during forward traversal.

toMultimap

template<class K, class V> auto toMultimap();

Builds an ordered multimap from the selected fields, retaining repeated keys and all corresponding values.

count

size_t count() noexcept;

Returns the committed row count. Pending insertions and deletions on this handle are reflected only after commit.

CDatabase

class CDatabase

Methods

CDatabase

CDatabase(const cstr& path, bool create);

Creates a new database directory when create is true or opens an existing database otherwise. Acquires an exclusive database lock; an existing create path or an already-open database is an error.

~CDatabase

~CDatabase();

Performs shutdown and attempts to persist committed state. Shutdown failures are reported to the configured error stream rather than escaping destruction.

setSaveInterval

void setSaveInterval(double secs);

Sets the interval in seconds for background persistence of committed state. Zero disables periodic saves; negative or non-finite intervals are rejected.

shutdown_

void shutdown_();

Stops periodic saving, saves committed state, and releases database resources. Table handles must no longer be used; this does not commit uncommitted changes held by those handles.

setErrorStream

void setErrorStream(std::ostream& estr);

Sets the borrowed stream used for background and shutdown diagnostics. Keep the stream alive until database shutdown has completed.

exists

template<class R> bool exists();

Checks whether the schema’s named table exists with the expected row-ID width. It does not create or return a table handle.

createTable

template<class R> auto createTable();
template<class RI> auto createTable(const cvar& schema, const cstr& name);

Creates the named table and returns an owning table handle. Typed overloads derive the name from the row schema.

getTable

template<class R> std::unique_ptr<CTable<R>> getTable();
template<class RI> std::unique_ptr<CVarTable<RI>> getTable(const cvar& schema, const cstr& name);

Opens an existing table and returns an owning handle tied to this database.

eraseTable

void eraseTable(const cstr& tableName);

Deletes a named table and its backing storage. Release all handles to that table before removing it.

renameTable

template<class RI> void renameTable(const cstr& oldName, const cstr& newName);

Renames an existing table of row-ID type RI. The source must exist and the destination must not exist; a row-ID width mismatch is rejected.

setMemoryLimit

void setMemoryLimit(size_t megabytes);

Sets a positive cache limit in megabytes. This controls database page caching rather than an absolute limit on total process memory.

compact

template<class R> void compact(size_t commitInterval = 10000);

Rewrites live rows to reclaim deleted storage. Use a positive commit interval; row IDs may change.

Free functions & types

Types, constants & data

#define cquery(T, R)