mabain/README.md

   1 # mabain
   2
   3 [![Build Status](https://travis-ci.org/chxdeng/mabain.svg?branch=master)](https://travis-ci.org/chxdeng/mabain)
   4
   5 [![Coverage Status](https://coveralls.io/repos/github/chxdeng/mabain/badge.svg)](https://coveralls.io/github/chxdeng/mabain)
   6
   7 ## Mabain: a key-value store library
   8
   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.
  13
  14 ### Shared Memory and Memcap
  15
  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.
  20
  21 ### Multi-Thread/Multi-Process Concurrency
  22
  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
  27 Caveats below)*
  28
  29 ### Multi-Thread/Multi-Process Insertion/Update
  30
  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.
  36
  37 ## Build and Install Mabain Library
  38
  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++.
  43
  44 ### Native Build & Install
  45
  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/)
  51
  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:
  55
  56 ```
  57 make build
  58 ```
  59
  60 #### (Optional) - Run the unit tests
  61
  62 If you would like to run the unit tests you will need some additional dependencies:
  63
  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/)
  69
  70 The command :
  71
  72 ```
  73 make unit-test
  74 ```
  75 ### Install Mabain
  76
  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:
  80
  81 ```
  82 make install
  83 ```
  84
  85 ### Docker Build
  86
  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:
  89
  90     make docker
  91
  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.
  95
  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.
  99
 100 ```
 101 docker run -it --rm -v$(pwd)/data:/data chxdeng/mabain /usr/local/bin/mbc -d /data -w
 102 ```
 103
 104 This should drop you into the mbc command-line client. It should look something
 105 like this:
 106
 107 ```
 108 mabain 1.1.0 shell
 109 database directory: /data/
 110 >>
 111 ```
 112
 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.
 117
 118 ## Mabain Command-Line Client
 119
 120 The command-line client source is in the `binaries` directory. It is installed
 121 into $MABAIN_INSTALL_DIR/bin via `make install`.
 122
 123 ```
 124 Usage: mbc -d mabain-directory [-im index-memcap] [-dm data-memcap] [-w] [-e query] [-s script-file]
 125
 126 -d   mabain databse directory
 127 -im  index memcap
 128 -dm  data memcap
 129 -w   running in writer mode
 130 -e   run query on command line
 131 -s   run queries in a file
 132 ```
 133
 134 ## Examples
 135
 136 Please follow these steps to run the examples
 137
 138 1. Build and install mabain library
 139 ```
 140 make clean build install
 141 ```
 142
 143 2. Build examples
 144 ```
 145 cd ./examples
 146 make
 147 ```
 148 3. Create the temporary database directory for examples
 149 ```
 150 mkdir ./tmp_dir
 151 ./mb_insert_test
 152 ```
 153
 154 ## Caveats
 155
 156 * Only one writer is allowed. However, multiple readers can be running
 157   concurrently.
 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
 165   endian machines.
 166
 167 ## License
 168
 169 Copyright (C) 2017 Cisco Inc.
 170
 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.
 174
 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.
 179
 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/>.
 182
 183 [![License: GPL
 184 v2](https://img.shields.io/badge/License-GPL%20v2-blue.svg)](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)