README.md

   1 [![EJDB](http://ejdb.org/_images/ejdblogo3.png)](http://ejdb.org)
   2
   3 [EJDB v1.2.12 released (2017-21-03)](https://github.com/Softmotions/ejdb/releases/tag/v1.2.12)
   4
   5 Embedded JSON Database engine C library (libejdb)
   6 =================================================
   7
   8 [![Join the chat at https://gitter.im/Softmotions/ejdb](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Softmotions/ejdb?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   9
  10 **See http://ejdb.org**
  11
  12 It aims to be a fast [MongoDB](http://mongodb.org)-like library
  13 **which can be embedded into C/C++, .Net, NodeJS, Python, Lua, Go, Java
  14 and Ruby applications under terms of LGPL license.**
  15
  16 EJDB is the C library based on modified
  17 version of [Tokyo Cabinet](http://fallabs.com/tokyocabinet/).
  18
  19 JSON representation of queries and data implemented with API based on
  20 [C BSON](https://github.com/mongodb/mongo-c-driver/tree/master/src/)
  21
  22 **[Roadmap and thoughts for the next major EJDB 2.0 release](https://github.com/Softmotions/ejdb/issues/183)**
  23
  24 Features
  25 ========
  26 * LGPL license allows you to embed this library into proprietary software
  27 * Simple C libejdb library can be easily embedded into any software
  28 * Node.js/Python/Lua/Java/Ruby/.Net/Go/Pike/Mathlab/AdobeAIR bindings available
  29 * MongoDB-like queries and overall philosophy.
  30 * [Collection joins](https://github.com/Softmotions/ejdb/wiki/Collection-joins)
  31
  32 Usage
  33 =====
  34
  35 One snippet intro
  36 -----------------------------------
  37
  38 ```C
  39 #include <ejdb/ejdb.h>
  40
  41 static EJDB *jb;
  42
  43 int main() {
  44     jb = ejdbnew();
  45     if (!ejdbopen(jb, "addressbook", JBOWRITER | JBOCREAT | JBOTRUNC)) {
  46         return 1;
  47     }
  48
  49     //Get or create collection 'contacts'
  50     EJCOLL *coll = ejdbcreatecoll(jb, "contacts", NULL);
  51
  52     bson bsrec;
  53     bson_oid_t oid;
  54
  55     //Insert one record:
  56     //JSON: {'name' : 'Bruce', 'phone' : '333-222-333', 'age' : 58}
  57     bson_init(&bsrec);
  58     bson_append_string(&bsrec, "name", "Bruce");
  59     bson_append_string(&bsrec, "phone", "333-222-333");
  60     bson_append_int(&bsrec, "age", 58);
  61     bson_finish(&bsrec);
  62
  63     //Save BSON
  64     ejdbsavebson(coll, &bsrec, &oid);
  65     fprintf(stderr, "\nSaved Bruce");
  66     bson_destroy(&bsrec);
  67
  68     //Now execute query
  69     //QUERY: {'name' : {'$begin' : 'Bru'}} //Name starts with 'Bru' string
  70     bson bq1;
  71     bson_init_as_query(&bq1);
  72     bson_append_start_object(&bq1, "name");
  73     bson_append_string(&bq1, "$begin", "Bru");
  74     bson_append_finish_object(&bq1);
  75     bson_finish(&bq1);
  76
  77     EJQ *q1 = ejdbcreatequery(jb, &bq1, NULL, 0, NULL);
  78
  79     uint32_t count;
  80     TCLIST *res = ejdbqryexecute(coll, q1, &count, 0, NULL);
  81     fprintf(stderr, "\n\nRecords found: %d\n", count);
  82
  83     //Now print the result set records
  84     for (int i = 0; i < TCLISTNUM(res); ++i) {
  85         void *bsdata = TCLISTVALPTR(res, i);
  86         bson_print_raw(bsdata, 0);
  87     }
  88     fprintf(stderr, "\n");
  89
  90     //Dispose result set
  91     tclistdel(res);
  92
  93     //Dispose query
  94     ejdbquerydel(q1);
  95     bson_destroy(&bq1);
  96
  97     //Close database
  98     ejdbclose(jb);
  99     ejdbdel(jb);
 100     return 0;
 101 }
 102 ```
 103
 104 Assuming libejdb installed on your system you can place the code above in `csnippet.c` and build program:
 105
 106 ```sh
 107 gcc -std=c99 -Wall -pedantic  -c -o csnippet.o csnippet.c
 108 gcc -o csnippet csnippet.o -lejdb
 109 ```
 110
 111 C API
 112 =====
 113
 114 EJDB API exposed in **[ejdb.h](https://github.com/Softmotions/ejdb/blob/master/src/ejdb/ejdb.h)** C header file.
 115 JSON processing API: **[bson.h](https://github.com/Softmotions/ejdb/blob/master/src/bson/bson.h)**
 116
 117
 118 Building
 119 ========
 120
 121 Prerequisites
 122 -------------
 123
 124  * git
 125  * GNU make
 126  * cmake >= 2.8.12
 127  * gcc >= 4.7 or clang >= 3.4 C compiller
 128  * zlib-dev
 129
 130 Make
 131 ----
 132
 133 ```sh
 134 git clone https://github.com/Softmotions/ejdb.git
 135 cd ejdb
 136 mkdir build
 137 cd build
 138 cmake -DCMAKE_BUILD_TYPE=Release ../
 139 make
 140 make install
 141 # Or you can create tgz package:
 142 make package
 143 ```
 144
 145 ### CMake basic build(-D) options
 146
 147 ```
 148 // Build ejdb sample projects
 149 BUILD_SAMPLES:BOOL=ON
 150
 151 // Build shared libraries
 152 BUILD_SHARED_LIBS:BOOL=ON
 153
 154 // Build test cases
 155 BUILD_TESTS:BOOL=OFF
 156
 157 // Choose the type of build, options are: None(CMAKE_CXX_FLAGS or CMAKE_C_FLAGS used) Debug Release RelWithDebInfo.
 158 CMAKE_BUILD_TYPE:STRING=Release
 159
 160 // Install path prefix, prepended onto install directories.
 161 CMAKE_INSTALL_PREFIX:PATH=/usr/local
 162
 163 // Enable PPA package build
 164 ENABLE_PPA:BOOL=OFF
 165
 166 // Build .deb instalation packages
 167 PACKAGE_DEB:BOOL=OFF
 168
 169 // Build .tgz package archive
 170 PACKAGE_TGZ:BOOL=ON
 171
 172 // Upload debian packages to the launchpad ppa repository
 173 UPLOAD_PPA:BOOL=OFF
 174 ```
 175
 176 ### Building Windows libs
 177
 178 You need to checkout the [MXE cross build environment](http://mxe.cc)
 179 Then create/edit MXE settings file:
 180
 181 ```sh
 182 cd <mxe checkout dir>
 183 nano ./settings.mk
 184 ```
 185
 186 Save the following content in `settings.mk`:
 187
 188 ```
 189 JOBS := 1
 190 MXE_TARGETS := x86_64-w64-mingw32.static i686-w64-mingw32.static
 191 LOCAL_PKG_LIST := winpthreads pcre zlib lzo bzip2 cunit
 192 .DEFAULT local-pkg-list:
 193 local-pkg-list: $(LOCAL_PKG_LIST)
 194 ```
 195
 196 Build MXE packages:
 197
 198 ```sh
 199  cd <mxe checkout dir>
 200  make
 201 ```
 202
 203 Build libejdb windows binaries:
 204
 205 ```sh
 206 export MXE_HOME=<mxe checkout dir>
 207 cd <ejdb checkout dir>
 208 mkdir build-win32
 209 cd build-wind32
 210 cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../win64-tc.cmake ..
 211 make package
 212 ```
 213
 214 EJDB binary package installation
 215 ===================================
 216
 217 Ubuntu
 218 ------
 219
 220 ```sh
 221 sudo add-apt-repository ppa:adamansky/ejdb
 222 sudo apt-get update
 223 sudo apt-get install ejdb ejdb-dbg
 224 ```
 225