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 (the only Elixir SDK providing it)
• working re-connection handling that includes:
  • re-executing the 'on_auth' callback
  • re-establishing subscriptions to active live queries
• verbose logging
  • config :logger, :console, level: :debug
  • Surrealix.start_link(debug: [:trace])
• :telemetry events for request handling
• extensive and very maintainable (thanks to mneme) E2E tests against SurrealDB server (https://github.com/maxohq/surrealix/tree/main/lib/surrealdb)
• tests run in isolated databases, that are removed after each test completion, so there is no danger of overwriting any local development data

Usage

# {:ok, pid} = Surrealix.start_link(debug: [:trace]) ## for debugging!
{:ok, pid} = Surrealix.start_link()
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)

Handling reconnection

To properly deal with connection drops, provide an on_auth-callback when starting a Surrealix Socket. on_auth callbacks should include logic to authenticate the connection and select a namespace / database.

This callback is called in a non-blocking fashion, so it is important to wait until the on_auth-callback is finished. This is done via Surrealix.wait_until_auth_ready(pid) function, that checks auth status via busy-waiting.

Live queries that were setup via Surrealix.live_query(pid, sql, callback) function are registed on SocketState and will be re-established after a successful reconnection.

{:ok, pid} =
    Surrealix.start(
      on_auth: fn pid, _state ->
        IO.puts("PID: #{inspect(pid)}")
        Surrealix.signin(pid, %{user: "root", pass: "root"}) |> IO.inspect(label: :signin)
        Surrealix.use(pid, "test", "test") |> IO.inspect(label: :use)
      end
    )

# blocks until the `on_auth` callback is executed
Surrealix.wait_until_auth_ready(pid)

# now we can execute queries, that require auth
Surrealix.live_query(pid, "LIVE SELECT * FROM user;", fn data, query_id ->
  IO.inspect({data, query_id}, label: "callback")
end)

Surrealix.live_query(pid, "LIVE SELECT * FROM person;", fn data, query_id ->
  IO.inspect({data, query_id}, label: "callback")
end)

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
config :surrealix, backoff_max: 2000
config :surrealix, backoff_step: 50
config :surrealix, timeout: :infinity # default 5000
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.

Ref

• Websockex callbacks (Elixir)
• Websocket Text Protocol
• JS SDK for websockets
• Source code for the Websocket Text Protocol docs
• SurrealDB SQL statements
• SurrealDB functions

Support

License

The lib is available as open source under the terms of the MIT License.