elips::Database is the primary database class in the ELIPS engine. It manages persistent file descriptors, write-ahead logs (WAL), advisory file locking, and collection life-cycles.

Overview

A Database represents one open database instance bound to a directory path (or ":memory:"). It acts as the container and coordinator for all named Collection partitions within the database.

open() & Constructor

cpp

namespace elips {
    std::unique_ptr<Database> open(
        const std::string& path,
        const Config& config = Config{}
    );
}

The factory function elips::open() is the recommended way to open or create an ELIPS database instance.

path — File system directory path for disk-backed persistence, or ":memory:" for volatile in-memory operation.
config — Default Config applied to newly spawned collections.

Direct Constructor

cpp

Database(
    std::string path,
    Config config,
    bool persistent,
    std::optional<LockManager> lock = std::nullopt
);

Collection Management

cpp

Collection& collection(const std::string& name);
std::vector<std::string> list_collections() const;
Collection& adopt_collection(std::unique_ptr<Collection> collection);

collection(name) — Gets a reference to an existing collection or lazily creates a new collection with the instance's default Config.
list_collections() — Returns a vector containing the names of all active collections.
adopt_collection(collection) — Attaches a custom initialized Collection to the instance registry.

Transactions

cpp

Transaction begin_transaction();

Starts an atomic multi-vault write transaction. Returns a Transaction object.

query() (EQL)

cpp

std::vector<SearchResult> query(
    const std::string& eql,
    const std::map<std::string, Vector>& bindings = {}
);

Executes a declarative ELIPS Query Language (EQL) string against the database instance with vector binding parameters.

Maintenance & Checkpoints

cpp

void checkpoint();
void compact();
void vacuum();
void close();
void abandon() noexcept;

checkpoint() — Flushes memory-mapped pages and truncates the WAL log up to the latest sequence number.
compact() — Rewrites storage segment files on disk to eliminate unreferenced tombstones and shrink file sizes.
vacuum() — Reclaims deleted vector nodes within HNSW graph indices across all open collections.
close() — Safely seals all collections, flushes WAL, and releases process lock handlers.

Introspection & GPU

cpp

WAL* wal() const noexcept;
const Config& config() const noexcept;
const std::string& path() const noexcept;
bool persistent() const noexcept;
bool closed() const noexcept;

#ifdef ELIPS_GPU_ENABLED
gpu::GpuDeviceInfo gpu_info() const;
gpu::GpuMetricsSnapshot gpu_stats() const;
#endif

Thread Safety & Concurrency

Database is completely thread-safe. Concurrent calls to collection(), list_collections(), and checkpoint() across threads are serialized via internal recursive locks.