WebSocket connection to a SpacetimeDB database.
Manages the v2 BSATN binary WebSocket protocol lifecycle:
- Connects with optional JWT authentication
- Receives and decodes server messages
- Sends client messages (subscribe, call_reducer, etc.)
- Tracks request IDs for response correlation
- Handles reconnection
Usage
{:ok, conn} = Spacetimedbex.Connection.start_link(
host: "localhost:3000",
database: "my_db",
token: "optional-jwt-token",
handler: self()
)
# Subscribe to a table
Spacetimedbex.Connection.subscribe(conn, ["SELECT * FROM users"])
# Call a reducer
Spacetimedbex.Connection.call_reducer(conn, "create_user", args_bsatn)Messages are delivered to the handler process as {:spacetimedb, message} tuples.
Summary
Functions
Call a reducer with BSATN-encoded arguments.
Get the current connection state.
Execute a one-off SQL query.
Start a WebSocket connection to SpacetimeDB.
Subscribe to one or more SQL queries. Returns the query_set_id.
Unsubscribe from a query set.
Types
@type t() :: %Spacetimedbex.Connection{ base_backoff_ms: term(), compression: term(), connected: term(), connection_id: term(), database: term(), handler: term(), host: term(), identity: term(), max_backoff_ms: term(), max_reconnect_attempts: term(), next_query_set_id: term(), next_request_id: term(), pending_requests: term(), token: term() }
Functions
Call a reducer with BSATN-encoded arguments.
Get the current connection state.
Execute a one-off SQL query.
Start a WebSocket connection to SpacetimeDB.
Options
:host- Host and port (e.g., "localhost:3000"). Required.:database- Database name or identity. Required.:token- JWT auth token. Optional (server will mint one if omitted).:handler- PID to receive{:spacetimedb, msg}messages. Required.:compression- Compression preference::none,:gzip,:brotli. Default:none.:max_reconnect_attempts- Max reconnection attempts before giving up. Default 5.:base_backoff_ms- Base backoff time in ms (multiplied by attempt). Default 1000.:max_backoff_ms- Maximum backoff time in ms. Default 10000.:name- Optional process name registration.
Subscribe to one or more SQL queries. Returns the query_set_id.
Unsubscribe from a query set.