Surrealix

Lightweight, correct and up-to-date Elixir SDK for SurrealDB.

Why use Surrealix?

up-to-date on the Websocket API for SurrealDB (https://github.com/maxohq/surrealix/blob/main/gen/src/api.ts) - via code generation
minimal abstraction over WebSocket (text protocol) for SurrealDB
Elixir documentation shows raw examples from the SurrealDB docs, so that it's very clear what happens behind the covers. You can keep referring the official docs!
first-class support for live-query callbacks (currently the ONLY Elixir SDK)
:telemetry events for request handling
extensive and very maintainble (thanks to mneme) E2E tests against SurrealDB server (https://github.com/maxohq/surrealix/tree/main/lib/surrealdb)

Usage

# {:ok, pid} = Surrealix.start_link(namespace: "test", database: "test", debug: [:trace]) ## for debugging!
{:ok, pid} = Surrealix.start_link(namespace: "test", database: "test")
Surrealix.signin(pid, %{user: "root", pass: "root"})
Surrealix.use(pid, "test", "test")
Surrealix.query(pid, "SELECT * FROM person;")
Surrealix.query(pid, "SELECT * FROM type::table($table);", %{table: "person"})

## Example with live query callbacks
Surrealix.live_query(pid, "LIVE SELECT * FROM user;", fn data, query_id ->
  IO.inspect({data, query_id}, label: "callback")
end)

## Example with live query with DIFF
Surrealix.live_query(pid, "LIVE SELECT DIFF FROM user;", fn data, query_id ->
  IO.inspect({data, query_id}, label: "callback")
end)


# inspect currently registered live queries
Surrealix.all_live_queries(pid)

Telemetry

Currently library publishes only 3 events:

events = [
  [:surrealix, :exec_method, :start],
  [:surrealix, :exec_method, :stop],
  [:surrealix, :exec_method, :exception]
]

In the meta there is further information about the method name and the arguments, that were sent to SurrealDB server.

As example we provide a Surrealix.Telemetry.Logger, that logs those events to the console.

## Configure basic logger telemetry
Surrealix.Telemetry.Logger.setup()

Configuration

## in config.exs / runtime.exs file
# default 5000
config :surrealix, timeout: :infinity
config :surrealix, :conn,
  hostname: "0.0.0.0",
  port: 8000

Installation

If available in Hex, the package can be installed by adding surrealix to your list of dependencies in mix.exs:

def deps do
  [
    {:surrealix, "~> 0.1"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/surrealix.

Aknowledgements

Code foundation was taken from https://github.com/joojscript/surrealdb_ex. Since this package has not received any commits in the last 7 months (2023-10-31) and the issues are left uncommented, I have assumed that the maintainer is not interested in any contributions.