PitilessPeanut / IncludeDB

Tiny key/value-store in a single, embeddable C file. For games, small servers, sbc, etc...
9 stars 1 forks source link
c compile-time-testing embedded key-value key-value-database key-value-store single-header single-header-lib

IncludeDB

An stb-style #include-only single-header k/v store implemented in C99 with an emphasis on easy-of-use. Small file database (!) best suited for environments with limited resources or in situations where a more complex database library would be an overkill such as small games.

Use this in your Arduino/Playdate/WASM Game!!

Financing

This project is entirely self-financed and we NEED your support! Ensure smooth-sailing & regular updates by donating 🥜s below:

Buy Me A Peanut

lnbc169690n1pj2jm89pp5wxlx47arg3nu2sajfdu5uq3u2dgs0d5hvzhv60rv5lzu8h5h4z5qdqu2askcmr9wssx7e3q2dshgmmndp5scqzzsxqyz5vqsp52m4d5w2gwauz4nhn4jypempvq4wuxef7unvzgmfppggwpdpn5j3s9qyyssqveag435teq0uhfp4mgzxp8p2q534kans7ns4sgegvq5qrg628djjk4s3jnmu72d5wvnclm03ts5u883jv6jvqnj9847sk03yplj9thspdgp6v3

lnbc169690n1pj2jm89pp5wxlx47arg3nu2sajfdu5uq3u2dgs0d5hvzhv60rv5lzu8h5h4z5qdqu2askcmr9wssx7e3q2dshgmmndp5scqzzsxqyz5vqsp52m4d5w2gwauz4nhn4jypempvq4wuxef7unvzgmfppggwpdpn5j3s9qyyssqveag435teq0uhfp4mgzxp8p2q534kans7ns4sgegvq5qrg628djjk4s3jnmu72d5wvnclm03ts5u883jv6jvqnj9847sk03yplj9thspdgp6v3

bc1qpv63qlpec3x3lh2cejmr5audh2c6j2ar3ptvy235hld3f2wwzr5sg4qr5n

bc1qpv63qlpec3x3lh2cejmr5audh2c6j2ar3ptvy235hld3f2wwzr5sg4qr5n

bitcoincash:qzfy6xcw93s8605rywcwug3vpf5kmy5ywgw0lw5lj0

bitcoincash:qzfy6xcw93s8605rywcwug3vpf5kmy5ywgw0lw5lj0

LPM7ueXta6kFwCnBKd5viJDX2CN8eLsg3b

LPM7ueXta6kFwCnBKd5viJDX2CN8eLsg3b

47NF2hjeMXMMCHu6XNyMrWeJwkndaTNvGAKAQuy6v9wvNTHViVwi3BGTr8wy9U4aoNbDcLMEf7dVjNGvQacttGc3CjEJgP8

47NF2hjeMXMMCHu6XNyMrWeJwkndaTNvGAKAQuy6v9wvNTHViVwi3BGTr8wy9U4aoNbDcLMEf7dVjNGvQacttGc3CjEJgP8

🪨 Let's cook this stonesoup together!!! 🪨

Status

Attention!! This project is still alpha and many things have yet to be implemented:

Table of Contents

Building

A build process is not required, simply drop includedb.h into your project and use.

Generate

If needed, use python generate.py to create the "includedb.h" file

Demo

Building the example program can be done with just cc -o demo demo_includedb.c When run, a "hello.dat" file will be created.

Compile-time tests

If compiled as C++ a number of unit-tests will be executed during compilation. To disable this behaviour #define DISABLE_TESTS before #include "includedb.h"

Using

Attention This code is not yet production-ready! Proceed accordingly!

Configuration: More options, such as setting a different malloc()/free() are available. Take a look inside includedb.h

// Chunk size is 256 by default. This is the MINIMUM size
// a key/value pair is going to take up. To set a custom value:
#define INCLUDEDB_CHUNK_SIZE 1024 // Optional

// After that add
#define INCLUDEDB_IMPLEMENTATION // Required!
// And finally
#include "includedb.h"

Usage:

// Create new or open existing. NULL is returned 
// in case the file couldn't be opened or created:
includeDB *mydb = includedb_open("hello.dat");

// read/write/etc...

// Make sure to call close() after done using:
includedb_close(mydb);

The database can also be operated entirely during compile time, providing you with a compile-time key/value store.

Attention! All operations are synchronous, locking has not yet been implemented. See above^ to help financing!

Super easy to use, only 7 functions needed:

includedb_put(instance, key, keylen, val, vallen)
includedb_get(instance, key, keylen, vallen)
includedb_next(instance)
includedb_curGetKey(instance, keylen)
includedb_open(filename)
includedb_close(instance)
includedb_getError(instance)

WARNING! None of these are thread-safe (yet!) Make sure to avoid concurrent access*

*until I have found the time to fix this...

Screenshots

Javascript visualization

algo-visualize.js is provided and can be run on https://algorithm-visualizer.org/ to show the mechanism of the underlying algorithm.

visualization of the underlying algorithm on algorithm-visualizer.org

Known issues

Depending on available resources these will be fixed over time. Issues:

Contributing

I hope the code is somewhat readable and not too much of a mess. Either way contributions are very welcome, feel free to msg me or issue a request! Join: https://discord.gg/dJxnkNwE

Similar projects

IncludeDB is a "storage engine", not a full database. Designed specifically for small files (<250mb). Depending on your requirements we encourage you to check out these:

RocksDB High performance, log based k/v

LMDB Very popular

NuDB Header only k/v

SQLite Battle tested. Popular in browsers/etc.

Unqlite

Sparkey

Sponsors