Unlock speed where every write counts.

TidesDB is a light-weight C++ library that provides an embeddable, persistent key-value store for fast flash and ram storage. TidesDB has a robust feature-set, and was designed from the ground up to be a high-performance, low-latency storage engine. It is optimized for write and read-heavy workloads.

User Guide

Basic Usage

Initialize the LSMT:

#include "libtidesdb.h"
        
int main() {
    auto lsmt = TidesDB::LSMT::New("data_directory", std::filesystem::perms::owner_all, 1024 * 1024, 60, 4);
    // Use the LSMT instance
    lsmt->Put({1, 2, 3}, {4, 5, 6});
    auto value = lsmt->Get({1, 2, 3});
    lsmt->Close();
    return 0;
}

Insert a key-value pair:
TidesDB takes keys and values as vectors of bytes, there is no limit to key and or value size.

Writing to the same key updates the value.
```
lsmt->Put({1, 2, 3}, {4, 5, 6});
```

Retrieve a value by key:
```
auto value = lsmt->Get({1, 2, 3});
```

Delete a key-value pair:
```
lsmt->Delete({1, 2, 3});
```

Close the LSMT:
Flushes memtable to disk on close.

Commits any active transactions.
```
lsmt->Close();
```

API Guide

Classes and Methods

`TidesDB::LSMT`

Constructor:
- Parameters:
  - directory: The directory where the data is stored.
  - memtable_flush_size: The size of the memtable in bytes.
  - compaction_interval: The interval of sstables required to run compaction.
  - pager: The pager instance to use for reading and writing data.
  - sstables: A vector of SSTable instances to use for reading and writing data.
```
LSMT(const std::string &directory, int memtable_flush_size, int compaction_interval, const std::shared_ptr<Pager> &pager, const std::vector<std::shared_ptr<SSTable>> &sstables);
```

Static Method:
- Parameters:
  - directory: The directory where the data is stored.
  - directoryPerm: The permissions to set on the directory.
  - memtableFlushSize: The size of the memtable in bytes.
  - compactionInterval: The interval of sstables required to run compaction.
```
static std::unique_ptr<LSMT> New(const std::string &directory, std::filesystem::perms directoryPerm, int memtableFlushSize, int compactionInterval);
```

Methods:

Put: Inserts a key-value pair into the LSMT.
Delete: Deletes a key-value pair from the LSMT.
Get: Retrieves the value associated with a key from the LSMT.
NGet: Retrieves the key-value pairs not associated with a key from the LSMT.
LessThan: Retrieves the key-value pairs with keys less than a given key from the LSMT.
GreaterThan: Retrieves the key-value pairs with keys greater than a given key from the LSMT.
Range: Retrieves the key-value pairs with keys in a given range from the LSMT.
NRange: Retrieves the key-value pairs with keys not in the given range from the LSMT.
LessThanEq: Retrieves the key-value pairs with keys less than or equal to a given key from the LSMT.
GreaterThanEq: Retrieves the key-value pairs with keys greater than or equal to a given key from the LSMT.
Close: Closes the LSMT and flushes the memtable to disk.
BeginTransaction: Begins a transaction on the LSMT.
CommitTransaction: Commits a transaction on the LSMT.
RollbackTransaction: Rolls back a transaction on the LSMT.

bool Put(const std::vector<uint8_t>& key, const std::vector<uint8_t>& value);
bool Delete(const std::vector<uint8_t>& key);
std::vector<uint8_t> Get(const std::vector<uint8_t>& key);
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> NGet(const std::vector<uint8_t>& key) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> LessThan(const std::vector<uint8_t>& key) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> GreaterThan(const std::vector<uint8_t>& key) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> Range(const std::vector<uint8_t>& start, const std::vector<uint8_t>& end) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> NRange(const std::vector<uint8_t>& start, const std::vector<uint8_t>& end) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> LessThanEq(const std::vector<uint8_t>& key) const;
std::vector<std::pair<std::vector<uint8_t>, std::vector<uint8_t>>> GreaterThanEq(const std::vector<uint8_t>& key) const;
void Close();
Transaction* BeginTransaction();
bool CommitTransaction(Transaction* tx);
void RollbackTransaction(Transaction* tx);

`TidesDB::Pager`

Constructor:

Pager(const std::string &filename, std::ios::openmode mode);

Methods:

int64_t Write(const std::vector<uint8_t> &data);
std::vector<uint8_t> Read(int64_t page_number);
int64_t PagesCount();

`TidesDB::AVLTree`

Methods:

void insert(const std::vector<uint8_t>& key, const std::vector<uint8_t>& value);
void deleteKV(const std::vector<uint8_t>& key);
std::vector<uint8_t> Get(const std::vector<uint8_t>& key);
void inOrderTraversal(std::function<void(const std::vector<uint8_t>&, const std::vector<uint8_t>&)> func);
void clear();

`TidesDB::Transaction`

Methods:

void AddPut(const std::vector<uint8_t> &key, const std::vector<uint8_t> &value);
void AddDelete(const std::vector<uint8_t> &key);

`TidesDB::Wal`

Constructor:
```
Wal(Pager* pager);
```
Methods:
- WriteOperation: Writes an operation to the WAL.
- Recover: Recovers LSMT from WAL
- Close: Closes the WAL.
```
bool WriteOperation(const Operation& op) const;
bool Recover(LSMT &lsmt) const
void Close() const;
```

Enumerations

`TidesDB::OperationType`

Values:
```
OpPut,
OpDelete
```

Utility Functions

ConvertToUint8Vector:

std::vector<uint8_t> ConvertToUint8Vector(const std::vector<char>& input);

ConvertToCharVector:

std::vector<char> ConvertToCharVector(const std::vector<uint8_t>& input);

Example

#include "libtidesdb.h"
        
int main() {
    auto lsmt = TidesDB::LSMT::New("data_directory", std::filesystem::perms::owner_all, 1024 * 1024, 60, 4);
    lsmt->Put({1, 2, 3}, {4, 5, 6});
    auto value = lsmt->Get({1, 2, 3});
    lsmt->Close();
    return 0;
}

This guide provides a basic overview of how to use the TidesDB library. For more detailed information, refer to the source code and comments within the library.