3 [![Build Status](https://travis-ci.org/chxdeng/mabain.svg?branch=master)](https://travis-ci.org/chxdeng/mabain)
5 [![Coverage Status](https://coveralls.io/repos/github/chxdeng/mabain/badge.svg)](https://coveralls.io/github/chxdeng/mabain)
7 ## Mabain: a key-value store library
9 Mabain is a light-weighted C++ library that provides a generic key-value store
10 based on a radix tree implementation. It supports multi-thread and multi-process
11 concurrency *(see Caveats below)*. Mabain can be used for exact and common
12 prefix key match. Please see the examples in the `examples` directory.
14 ### Shared Memory and Memcap
16 Mabain stores all data on disk. However, you can specify how much data can be
17 mapped to shared memory using the memcap option. The memcap can be specified for
18 the key space and the value space. For example see the `-km` and `-dm` options to
19 the Mabain command line client below.
21 ### Multi-Thread/Multi-Process Concurrency
23 Full multi-thread/multi-process concurrency is supported. Concurrent insertion
24 and queries are supported internally using a lock-free mechanism. Programs using
25 the library DO NOT need to perform any locking on concurrent insertion and
26 lookup in the multi-thread or multi-process reader/writer scenario. *(see
29 ### Multi-Thread/Multi-Process Insertion/Update
31 When using mabain only one writer is allowed. However, all reader threads/processes can
32 perform DB insertion/update using asynchronous queue in shared memory if the writer
33 has ASYNC_WRITER_MODE specified in the option when opening the DB. In this case, a separate
34 thread in the writer process is started for internal DB operations. All DB writing
35 operations are performed sequentially in this thread.
37 ## Build and Install Mabain Library
39 We now have two different build options. First is the traditional "Native
40 Build", and *experimentally* a Docker build based on the very slim [Alpine
41 Linux](https://wiki.alpinelinux.org/wiki/Docker) and
42 [MSCL](https://www.musl-libc.org/) instead of glibc++.
44 ### Native Build & Install
46 #### Build/Runtime Dependencies
47 1. [GNU ncurses](https://www.gnu.org/software/ncurses/)
48 2. [GNU readline](https://www.gnu.org/software/ncurses/)
49 3. [GLIBC](https://www.gnu.org/software/libc/)
50 4. [g++ Compiler that supports C++11](https://gcc.gnu.org/)
52 You should be able to build Mabain on any modern linux machines. To build and
53 install, ensure you meet the dependency requirements called out above run
54 following command in the top level of your git clone:
60 #### (Optional) - Run the unit tests
62 If you would like to run the unit tests you will need some additional dependencies:
64 ##### Unit Test dependencies
65 1. [Google Test](https://github.com/google/googletest)
66 2. [OpenSSL](https://www.openssl.org/)
67 3. [gcovr & gcov](https://github.com/gcovr/gcovr)
68 4. [Gtest Tap Listener](https://github.com/kinow/gtest-tap-listener/)
77 By default, Mabain will atttempt to install into `/usr/local/`. If you would
78 like to override this behavior define the `MABAIN_INSTALL_DIR` variable before
79 running the following command:
87 You can skip the previous build step if you would like to just build for a
88 docker environment. From the top level of your repository clone just run:
92 This will kick off a two stage build process. We will spin up a build container
93 with all the build time dependencies. Once the build is complete, a thin
94 container image is build with just the run-time dependencies.
96 This image is intended to serve as a base layer for an application that would
97 like to leverage Mabain. However, we can certainly validate that the docker
98 container built properly.
101 docker run -it --rm -v$(pwd)/data:/data chxdeng/mabain /usr/local/bin/mbc -d /data -w
104 This should drop you into the mbc command-line client. It should look something
109 database directory: /data/
113 We expose a VOLUME from the image `/data` where you should bind mount persistent
114 storage. In the above command I have a `data` sub-directory in my current
115 directory that I mount to `/data`. This way, my database is created in the host
116 filesystem and persists between instantiation of containers based on this image.
118 ## Mabain Command-Line Client
120 The command-line client source is in the `binaries` directory. It is installed
121 into $MABAIN_INSTALL_DIR/bin via `make install`.
124 Usage: mbc -d mabain-directory [-im index-memcap] [-dm data-memcap] [-w] [-e query] [-s script-file]
126 -d mabain databse directory
129 -w running in writer mode
130 -e run query on command line
131 -s run queries in a file
136 Please follow these steps to run the examples
138 1. Build and install mabain library
140 make clean build install
148 3. Create the temporary database directory for examples
156 * Only one writer is allowed. However, multiple readers can be running
158 * Mabain DB handle is not thread-safe. Each thread must have open its own DB
159 instance when Using in multi-thread context.
160 * The longest key supported is 256 bytes.
161 * The value/data size can not be bigger than 32767 bytes.
162 * Using Mabain on network storage (NAS, SAN, NFS, SMB, etc..) has not been
163 tested. Your mileage may vary
164 * Please use `-D__BIG__ENDIAN__` in compilation flags when using Mabain on big
169 Copyright (C) 2017 Cisco Inc.
171 This program is free software: you can redistribute it and/or modify
172 it under the terms of the GNU General Public License, version 2,
173 as published by the Free Software Foundation.
175 This program is distributed in the hope that it will be useful,
176 but WITHOUT ANY WARRANTY; without even the implied warranty of
177 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
178 GNU General Public License for more details.
180 You should have received a copy of the GNU General Public License
181 along with this program. If not, see <http://www.gnu.org/licenses/>.
184 v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)