EJDB2 Embedded JSON Database for C Applications

EJDB2's Embedded JSON Storage Boundary

EJDB2 addresses applications that need to persist and query structured JSON documents inside a native process. Its intended users include C developers building applications or services that want database-style filtering, updates, projections, sorting, and joins without managing a separate database server. The repository describes a C11 API and a single-file database, with persistent storage provided by IOWOW. That makes the library relevant to desktop, mobile, embedded-adjacent, or service workloads where embedding is preferable to operating another process.

The database stores JSON documents in collections. A query can target a collection, descend through JSON paths, match values, combine conditions, update matching records, select returned fields, and control result ordering. This is materially different from treating a JSON file as an opaque text document. EJDB2 provides a query layer over JSON structures rather than requiring the application to implement every traversal and mutation rule.

The scope is still that of an embeddable engine, not a general relational database. The documented data model and query language are JSON-oriented. The README does not present SQL compatibility, a transaction model, a schema definition workflow, or a replication architecture. Applications whose requirements depend on those features would need evidence beyond this repository description before selecting EJDB2.

IOWOW, IWNET, and EJDB2 Request Flow

The repository identifies three layers. EJDB2 is the JSON database engine and query surface. IOWOW is the persistent key/value storage engine underneath it. IWNET supplies the HTTP and WebSocket endpoint functionality when the `jbs` server is used. This separation matters when judging integration cost: a C application can use the native C API, while a client-facing application can use the network endpoint instead of embedding every database operation in the same process.

JQL is inspired by XPath and Unix shell pipes. Its grammar has filters followed by optional apply, projection, and option stages. Filters select documents or nodes within collections. Apply operations can insert, upsert, or delete matching documents. Projections select `all` fields or particular JSON paths, and query options include `skip`, `limit`, `count`, `noidx`, `inverse`, and `ORDERBY`. Placeholders can use either a named form such as `:placeholder_name` or positional `?` placeholders.

The `**` path form matches object keys at arbitrary nesting depth, while `*` matches keys at one specified level. The grammar also defines comparison operators, including `eq`, `gte`, `lte`, `gt`, `lt`, `in`, `ni`, and `re`, with optional negation. The repository links the formal parser grammar in `src/jql/jqp.leg`, so the query syntax has a source file rather than only informal examples. Collection joins are also listed as a supported feature, although the README excerpt does not show a complete join query.

Building EJDB2 with Autark on Linux, macOS, or FreeBSD

The documented source build requires Linux, macOS, or FreeBSD, a `gcc` or `clang` compiler, and `pkgconf` or `pkg-config`. The project provides `build.sh`, which is documented as the build entry point through Autark. A first local build can be started with the following command.

./build.sh

This builds the project from the repository sources. The README does not provide expected output for a successful build, so the concrete verification available in the documentation is the test build rather than an invented terminal message.

The test build enables `EJDB_RUN_TESTS` and runs the documented test cases:

./build.sh -DEJDB_RUN_TESTS=1

The repository also documents AddressSanitizer and UndefinedBehaviorSanitizer builds:

./build.sh -DENABLE_ASAN=1 -DEJDB_RUN_TESTS=1
./build.sh -DENABLE_UBSAN=1 -DEJDB_RUN_TESTS=1

For a local installation under the user's home directory, the README gives this prefix form:

./build.sh --prefix=$HOME/.local

The README does not document package-manager packages, signed release artifacts, a Windows source-build procedure, or a complete installation guide for Android, iOS, Flutter, React Native, Java, Dart, Node.js, or Swift. Those topics appear as repository topics or bindings, but the excerpt does not give enough instructions to turn them into a verified installation tutorial.

Starting EJDB2's HTTP and WebSocket Example

The quickest documented first use is the `jbs` server. It exposes EJDB2 through HTTP and WebSocket endpoints, and the README uses that interface to create a small JSON collection interactively. Start the server with an access token:

./jbs -a 'myaccess01'

The README shows the endpoint at `localhost:9191`. The command output is an example from the documentation, not a result of executing the project here. The server creates or opens the database according to the `jbs` implementation, and the example subsequently reports a `db.jb` file.

Create `sample.json` containing the documented family document:

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 28,
  "pets": [
    {"name": "Rexy rex", "kind": "dog", "likes": ["bones", "jumping", "toys"]},
    {"name": "Grenny", "kind": "parrot", "likes": ["green color", "night", "toys"]}
  ]
}

Upload it to the `family` collection through HTTP:

curl -d '@sample.json' -H'X-Access-Token:myaccess01' -X POST http://localhost:9191/family

The WebSocket client shown by the README is `@softmotions/wscat`, connected with `wscat`. The example includes `k info` and `k get family 1`, where `k` is an arbitrary client key used for request correlation.

wscat -H 'X-Access-Token:myaccess01' -c http://localhost:9191

After connecting, send `k info` to inspect server information or `k get family 1` to retrieve the inserted record. The README does not document a complete command sequence for creating an index or running a JQL mutation through `wscat`, so those operations should be taken from the linked API documentation and JQL test cases rather than inferred here.

Native C API Versus the Network Endpoint

EJDB2 offers two documented access paths, and they solve different integration problems. The pure C API uses the headers `ejdb2.h` and `jql.h`. It keeps database operations in the native application and avoids requiring a separate `jbs` process. This is the more appropriate choice when the database is an implementation detail inside an application, subject to the project's own process lifecycle and error-handling requirements.

The `jbs` HTTP and WebSocket endpoint adds a network boundary. It can serve clients that communicate over TCP, as shown by `curl` and `wscat`. That makes it useful for a local tool, a service integration, or a client that should not link the C API directly. It also adds connection management, access-token handling, serialization, and network failure considerations that are absent from the direct C path.

The repository does not document a comparison with another JSON database or a benchmark against a competing store. Consequently, a product choice based on EJDB2 should be based on the documented integration boundary, required query features, supported platforms, and the application's own resource constraints. Choosing between the C API and `jbs` is the concrete architectural comparison supported by this repository.

EJDB2 Indexing, Backups, and Operational Limits

The README lists indexes and performance guidance as a dedicated JQL area, but the supplied excerpt does not show the index-creation syntax or quantify query latency. It therefore supports the conclusion that indexing is part of the feature set, not a measured performance claim. The query options include `noidx`, which is an explicit control over whether indexes are used, but the repository excerpt does not explain its exact selection semantics.

Online backups are listed as a core feature. The README does not document the backup command, restore procedure, consistency model, or recovery behavior, so those details cannot be turned into a runnable tutorial. A deployment that depends on backup validation must verify the missing operational contract before relying on it.

There are also project-management limits. The README says that the issues tracker is disabled and that pull requests are accepted. That statement gives contributors a contribution route, but it does not provide a public issue-based support path. The repository is not archived, and its last push was on 2026-10-13. Recent releases include `v2.92` on 2026-10-11, `v2.91` on 2026-09-08, and `v2.90` on 2026-08-30. The MIT license permits use under its terms, subject to the license file's conditions and notices.

Editorial conclusion

Application developers should consider EJDB2 when an embedded C11 database, a single-file store, and JQL-driven JSON operations match their requirements. Projects needing SQL compatibility, a documented support channel, or an independently confirmed cross-platform build plan should verify those constraints first. For EJDB2, the first checks are the required compiler, `pkgconf` or `pkg-config`, and the intended IOWOW and IWNET integration path.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Softmotions/ejdb on GitHub