README.md

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