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!!
This project is entirely self-financed and we NEED your support! Ensure smooth-sailing & regular updates by donating 🥜s below:
lnbc169690n1pj2jm89pp5wxlx47arg3nu2sajfdu5uq3u2dgs0d5hvzhv60rv5lzu8h5h4z5qdqu2askcmr9wssx7e3q2dshgmmndp5scqzzsxqyz5vqsp52m4d5w2gwauz4nhn4jypempvq4wuxef7unvzgmfppggwpdpn5j3s9qyyssqveag435teq0uhfp4mgzxp8p2q534kans7ns4sgegvq5qrg628djjk4s3jnmu72d5wvnclm03ts5u883jv6jvqnj9847sk03yplj9thspdgp6v3
Attention!! This project is still alpha and many things have yet to be implemented:
- mmap
- Support for concurrent read
- Support for thread-safe write
- Proper Windows support
- *delete()*ing a key/value pair
- recover keys
- benches
- maybe more stuff, I'm open for suggestions...
- A logo is needed! If you would like to volunteer to make one that would be super appreciated!!!
A build process is not required, simply drop includedb.h into your project and use.
If needed, use python generate.py to create the "includedb.h" file
Building the example program can be done with just cc -o demo demo_includedb.c When run, a "hello.dat" file will be created.
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"
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...
algo-visualize.js is provided and can be run on https://algorithm-visualizer.org/ to show the mechanism of the underlying algorithm.
Depending on available resources these will be fixed over time. Issues:
- 'includedb_put()' may call 'includedb__write()' with uninitialized data
- bloomfilters implemented but not used
- node promotion overflow bug
- missing tests
- missing locks (threads)
- missing locks (file)
- missing reverse cursor
- missing mmap
- missing error check/correction
- missing (good) documentation!
- much much more... ;(
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
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.