Introduction

JouleDB, JouleDB, energy-metered database, HDC primitives, joules per query.

This is the official documentation for JouleDB. The full source code lives in the private -core mirror; the public release surface is at openIE-dev/jouledb.

What you'll find here

Install, get the jouledb binary on your machine
Hello, JouleDB, first program in 30 seconds
Tutorial, a 30-minute hands-on guided tour
Reference, every feature, every flag, every API
Cookbook, task-oriented recipes
Design, why JouleDB exists and how it fits with the rest of openIE-dev

The openIE-dev ecosystem

JouleDB is one of five public openIE-dev projects. All five share a common substrate (flowG) and energy-metering layer (substrate-energy):

flow-g, the IR + runtime substrate
lux-lang, reactive language compiling to flowG
jmax, math-native language
joule-lang, energy-budgeted compiled language
jouledb, energy-metered database

License

JouleDB binaries, documentation and examples are licensed under MIT OR Apache-2.0 (see COPYRIGHT).

Install

Every channel installs the same thing: the jouledb server binary (crate joule-db-server). It serves HTTP on -p (default 8080), TCP on +1, the Postgres wire protocol on +2, and JWP on +3.

From source (works today)

cargo install --locked --git https://github.com/openIE-dev/jouledb joule-db-server
jouledb --version

The Release workflow builds jouledb-<version>-<target>.tar.gz (plus .sha256) for aarch64-apple-darwin, x86_64-apple-darwin, x86_64-unknown-linux-gnu, and aarch64-unknown-linux-gnu. Windows is experimental. Once a version is tagged:

cargo binstall jouledb            # the crates.io `jouledb` stub points binstall at these archives
# or
curl -fsSL https://github.com/openIE-dev/jouledb/releases/download/v0.1.0/jouledb-0.1.0-aarch64-apple-darwin.tar.gz | tar xz

Plain cargo install jouledb from crates.io only installs the stub, which prints these instructions. Use the --git form above to compile.

Homebrew

packaging/homebrew/jouledb.rb is the tap formula. Before a release exists: brew install --HEAD ./packaging/homebrew/jouledb.rb.

Docker

docker build -t jouledb .
docker run -e JOULEDB_JWT_SECRET=change-me -p 8080-8083:8080-8083 -v jdb:/data jouledb

Run and connect

jouledb -d ./data                 # loopback only, trust auth, like a local Postgres
psql "host=127.0.0.1 port=8082 user=postgres dbname=postgres sslmode=disable"

Binding to a non-loopback address (JOULEDB_BIND_HOST=0.0.0.0, as the container does) always turns auth on. Set JOULEDB_JWT_SECRET, which is also the pgwire password. Drivers tested in CI: psql, psycopg 3, SQLAlchemy 2, node-postgres, and pgJDBC (see tests/clients).

Hello, JouleDB

The minimum example. See the source in examples/hello/.

For a richer walkthrough, see the tutorial.

Tutorial

A 30-minute guided tour of JouleDB from install to a working program.

Tutorial chapters coming with v0.2.0. For now see examples/ for runnable code.

Reference

Complete API, syntax, and runtime reference.

Reference chapters coming with v0.2.0. For embedding APIs see docs.rs/jouledb.

Cookbook

Task-oriented recipes.

Cookbook recipes coming with v0.2.0.

Why JouleDB

JouleDB exists because [reasoning forthcoming with v0.2.0 docs].

Position in the openIE-dev ecosystem

See How it fits.

How JouleDB fits the openIE ecosystem

Five public projects share a common substrate:

                       lux-lang   jmax    joule-lang
                            \     |     /
                             \    |    /
                              ▼   ▼   ▼
                             flow-g  ←  ← ← jouledb (metered persistence)
                                ▲
                                │
                          substrate-energy
                              (joules)

[Detailed design discussion in v0.2.0 docs.]