README.md

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