Spacetimedbex

SpacetimeDB client library for Elixir.

Connects to SpacetimeDB via the v2 BSATN binary WebSocket protocol, providing real-time subscriptions, reducer calls, a local ETS-backed client cache, an HTTP REST client, Phoenix PubSub integration, and code generation.

Features

Module	Description
`Spacetimedbex.BSATN`	Binary codec — encoder, decoder, value encoder
`Spacetimedbex.Protocol`	v2 client/server message encoding and decoding
`Spacetimedbex.Connection`	WebSocket connection with auto-reconnect and backoff
`Spacetimedbex.Schema`	Schema fetcher and parser (tables, reducers, typespace)
`Spacetimedbex.ClientCache`	ETS-backed local mirror of subscribed tables
`Spacetimedbex.Client`	High-level client with callbacks and auto-encoding
`Spacetimedbex.Http`	HTTP REST client for all v1 API endpoints
`Spacetimedbex.Phoenix`	Phoenix PubSub adapter for broadcasting events
`Spacetimedbex.Codegen`	Code generation from schema
`mix spacetimedb.gen`	Mix task to generate structs, reducers, and client

Installation

# mix.exs
def deps do
  [
    {:spacetimedbex, "~> 0.1.2"}
  ]
end

Documentation | Hex | GitHub

Quick Start

High-Level Client (recommended)

Define a client module with callbacks:

defmodule MyApp.SpaceClient do
  use Spacetimedbex.Client

  def config do
    %{
      host: "localhost:3000",
      database: "my_db",
      subscriptions: ["SELECT * FROM users"]
    }
  end

  def on_connect(_identity, _conn_id, token, state) do
    {:ok, Map.put(state, :token, token)}
  end

  def on_insert("users", row, state) do
    IO.puts("New user: #{inspect(row)}")
    {:ok, state}
  end

  def on_update("users", old_row, new_row, state) do
    IO.puts("Updated: #{inspect(old_row)} → #{inspect(new_row)}")
    {:ok, state}
  end

  def on_delete("users", row, state) do
    IO.puts("Removed: #{inspect(row)}")
    {:ok, state}
  end
end

Start it and interact:

{:ok, pid} = Spacetimedbex.Client.start_link(MyApp.SpaceClient, %{})

# Call a reducer (auto-encodes args via schema)
Spacetimedbex.Client.call_reducer(pid, "create_user", %{"name" => "Alice", "age" => 30})

# Query the local cache
Spacetimedbex.Client.get_all(pid, "users")
Spacetimedbex.Client.find(pid, "users", 1)

# One-off SQL query via WebSocket
Spacetimedbex.Client.query(pid, "SELECT * FROM users WHERE age > 25")

# Unsubscribe from a query set
Spacetimedbex.Client.unsubscribe(pid, query_set_id)

Client Callbacks

All callbacks are optional except config/0:

Callback	When it fires
`on_connect(identity, conn_id, token, state)`	Initial connection established
`on_subscribe_applied(table, rows, state)`	Subscription data arrives
`on_insert(table, row, state)`	Row inserted
`on_delete(table, row, state)`	Row deleted
`on_update(table, old_row, new_row, state)`	Row replaced (same PK deleted + inserted)
`on_transaction(changes, state)`	Full transaction — return `{:ok, state, :skip_row_callbacks}` to suppress per-row callbacks
`on_reducer_result(request_id, result, state)`	Reducer completes
`on_unsubscribe_applied(query_set_id, rows, state)`	Unsubscribe completes
`on_query_result(request_id, result, state)`	One-off query result arrives
`on_disconnect(reason, state)`	Disconnected

Code Generation

Generate typed structs, reducer functions, and a client skeleton from a live database:

mix spacetimedb.gen \
  --host localhost:3000 \
  --database my_db \
  --module MyApp.SpacetimeDB \
  --output lib

Produces:

MyApp.SpacetimeDB.Tables.TableName — defstruct + @type t + from_row/1
MyApp.SpacetimeDB.Reducers — typed functions with @spec
MyApp.SpacetimeDB.Client — use Spacetimedbex.Client skeleton with config

HTTP REST Client

For operations that don't need a persistent WebSocket (identity management, database admin, ad-hoc SQL):

alias Spacetimedbex.Http

# Identity
{:ok, %{"identity" => id, "token" => token}} = Http.create_identity("localhost:3000")

# SQL query
{:ok, results} = Http.sql("localhost:3000", "my_db", "SELECT * FROM users", token)

# Call a reducer over HTTP
:ok = Http.call_reducer("localhost:3000", "my_db", "create_user", ["Alice", 30], token)

# Database management
{:ok, _} = Http.publish_database("localhost:3000", "my_db", wasm_binary, token)
{:ok, info} = Http.get_database("localhost:3000", "my_db")

Low-Level Connection

For full control over the WebSocket connection:

{:ok, conn} = Spacetimedbex.Connection.start_link(
  host: "localhost:3000",
  database: "my_db",
  handler: self()
)

# Messages arrive as {:spacetimedb, msg} tuples
receive do
  {:spacetimedb, {:identity, identity, conn_id, token}} -> :connected
end

Spacetimedbex.Connection.subscribe(conn, ["SELECT * FROM users"])
Spacetimedbex.Connection.call_reducer(conn, "create_user", bsatn_args)

Architecture

BSATN Codec

Binary SpacetimeDB Algebraic Type Notation — a compact little-endian binary format:

Integers: u8..u256, i8..i256 (little-endian)
Floats: f32, f64 (IEEE 754, little-endian)
Strings/Bytes: u32 length prefix + raw data (UTF-8 validated)
Arrays: u32 count prefix + concatenated elements
Products (structs): fields concatenated in order
Sums (enums): u8 variant tag + payload

Protocol (v2)

Client sends: Subscribe, Unsubscribe, OneOffQuery, CallReducer, CallProcedure.

Server sends (with 1-byte compression envelope): InitialConnection, SubscribeApplied, UnsubscribeApplied, SubscriptionError, TransactionUpdate, OneOffQueryResult, ReducerResult, ProcedureResult.

OTP Design

Application
├── Connection (WebSockex) — WebSocket with auto-reconnect
├── ClientCache (GenServer) — ETS-backed row storage
├── Schema — HTTP schema fetch + parse
└── Client (GenServer) — ties it all together with callbacks

Development

mix deps.get          # Install dependencies
just test             # Unit tests (no server needed)
just test-all         # All tests (requires SpacetimeDB on :3000)
just check            # Compile (strict) + test + credo
just shell            # iex -S mix

See justfile for all available commands.

License

MIT

Next Page → LICENSE