image:[License,link="https://github.com/hyperpolymath/palimpsest-license"]

FormDB BEAM

BEAM (Erlang/Gleam/Elixir) bindings for FormDB - the narrative-first database.

Overview

FormDB BEAM provides native bindings to FormDB for the BEAM ecosystem:

• Gleam - Type-safe functional interface

• Erlang - Low-level NIF bindings

• Elixir - (Coming soon)

All data is passed as CBOR-encoded binaries for maximum efficiency.

Installation

Gleam

Add to your gleam.toml:

[dependencies]
formdb_beam = ">= 0.1.0"

Erlang (rebar3)

Add to your rebar.config:

{deps, [
    {formdb_beam, {git, "https://github.com/hyperpolymath/formdb-beam.git", {tag, "v0.1.0"}}}
]}.

Quick Start

Gleam

import formdb_beam/client

pub fn main() {
  // Connect to database
  let assert Ok(conn) = client.connect("/path/to/db")

  // Get version
  let #(major, minor, patch) = client.version()
  io.println("FormDB v" <> int.to_string(major) <> "." <> int.to_string(minor))

  // Execute in transaction
  let assert Ok(result) = client.with_transaction(conn, client.ReadWrite, fn(txn) {
    // Your operations here
    client.apply_operation(txn, cbor_encoded_op)
  })

  // Close connection
  let assert Ok(_) = client.disconnect(conn)
}

Erlang

% Open database
{ok, Db} = formdb_nif:db_open(<<"/path/to/db">>),

% Begin transaction
{ok, Txn} = formdb_nif:txn_begin(Db, read_write),

% Apply operation (CBOR-encoded)
{ok, ResultCbor, ProvenanceCbor} = formdb_nif:apply(Txn, OperationCbor),

% Commit
ok = formdb_nif:txn_commit(Txn),

% Close
ok = formdb_nif:db_close(Db).

API Reference

Gleam API

Function	Description
version()	Get FormDB version as #(Int, Int, Int)
connect(path)	Open database at path
disconnect(conn)	Close database connection
begin_transaction(conn, mode)	Start transaction (ReadOnly or ReadWrite)
commit(txn)	Commit transaction
abort(txn)	Abort transaction
apply_operation(txn, cbor)	Apply CBOR-encoded operation
get_schema(conn)	Get database schema (CBOR)
get_journal(conn, since)	Get journal entries since sequence
with_transaction(conn, mode, fn)	Execute with automatic commit/abort

Erlang NIF API

Function	Description
version/0	Get version as {Major, Minor, Patch}
db_open/1	Open database (binary path)
db_close/1	Close database
txn_begin/2	Begin transaction with mode atom
txn_commit/1	Commit transaction
txn_abort/1	Abort transaction
apply/2	Apply CBOR operation
schema/1	Get schema
journal/2	Get journal since sequence

Building

Prerequisites

• Zig >= 0.11.0

• Erlang/OTP >= 25.0

• FormDB library

Build NIF

cd native
make FORMDB_PATH=/path/to/formdb

Run Tests

gleam test

Architecture

┌─────────────────────────────────────┐
│  Gleam Application                  │
│  (formdb_beam/client)               │
├─────────────────────────────────────┤
│  Erlang NIF Module                  │
│  (formdb_nif.erl)                   │
├─────────────────────────────────────┤
│  Zig NIF Implementation             │
│  (formdb_nif.zig)                   │
├─────────────────────────────────────┤
│  FormDB C ABI                       │
│  (bridge.zig)                       │
├─────────────────────────────────────┤
│  FormDB Core                        │
│  (Forth/Factor)                     │
└─────────────────────────────────────┘

License

PMPL-1.0-or-later

Related Projects

• FormDB - The database engine

• FormBase - Airtable alternative built on FormDB