{"id":15010100,"url":"https://github.com/maxohq/surrealix","last_synced_at":"2025-04-09T18:04:22.034Z","repository":{"id":204786501,"uuid":"712649849","full_name":"maxohq/surrealix","owner":"maxohq","description":"A lean and correct Elixir SDK for SurrealDB","archived":false,"fork":false,"pushed_at":"2023-12-15T16:14:36.000Z","size":132,"stargazers_count":17,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T20:03:07.471Z","etag":null,"topics":["database","elixir","surrealdb","websocket"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maxohq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-31T22:40:01.000Z","updated_at":"2025-02-13T17:50:54.000Z","dependencies_parsed_at":"2023-11-09T22:33:29.866Z","dependency_job_id":"af4cdc6a-d6f1-48c9-b4bb-5bfaf496d42e","html_url":"https://github.com/maxohq/surrealix","commit_stats":null,"previous_names":["maxohq/surrealix"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxohq%2Fsurrealix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxohq%2Fsurrealix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxohq%2Fsurrealix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maxohq%2Fsurrealix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maxohq","download_url":"https://codeload.github.com/maxohq/surrealix/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248084183,"owners_count":21045123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","elixir","surrealdb","websocket"],"created_at":"2024-09-24T19:30:10.300Z","updated_at":"2025-04-09T18:04:22.018Z","avatar_url":"https://github.com/maxohq.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Surrealix\n\n[![CI](https://github.com/maxohq/surrealix/actions/workflows/ci.yml/badge.svg?style=flat)](https://github.com/maxohq/surrealix/actions/workflows/ci.yml)\n[![Hex.pm](https://img.shields.io/hexpm/v/surrealix.svg?style=flat)](https://hex.pm/packages/surrealix)\n[![Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg?style=flat)](https://hexdocs.pm/surrealix)\n[![Total Download](https://img.shields.io/hexpm/dt/surrealix.svg?style=flat)](https://hex.pm/packages/surrealix)\n[![License](https://img.shields.io/hexpm/l/surrealix.svg?style=flat)](https://github.com/maxohq/surrealix/blob/main/LICENCE)\n\n---\n\nLightweight, correct and up-to-date Elixir SDK for [SurrealDB](https://surrealdb.com/docs/integration/sdks).\n\n## Why use Surrealix?\n  - currently the most full-featured SurrealDB SKD for Elixir\n\n  - API\n    - up-to-date on the Websocket API for SurrealDB (https://github.com/maxohq/surrealix/blob/main/gen/src/api.ts) - via code generation\n    - minimal abstraction over [WebSocket (text protocol)](https://surrealdb.com/docs/integration/websocket/text) for SurrealDB\n    - 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!\n\n  - Live Queries\n    - the only Elixir SDK to provide first-class support for live-query callbacks\n\n  - Reconnection\n    - working re-connection handling that includes:\n      - re-executing the 'on_auth' callback\n      - re-establishing subscriptions for active live queries\n\n  - Logging\n    - verbose logging via:\n      - `config :logger, :console, level: :debug`\n      - `Surrealix.start_link(debug: [:trace])` (from WebSockex)\n\n  - Telemetry\n    - `:telemetry` events for request handling\n      - `Surrealix.Telemetry.Logger.setup()` for STDOUT events\n\n  - Testing\n    - extensive, readable and maintainable E2E test suite\n    - uses [mneme](https://github.com/zachallaun/mneme) to update inline snapshots without any effort\n    - tests run on isolated databases, that are removed after each test completion. Your local data stays safe!\n    - uses [maxo_test_iex](https://github.com/maxohq/maxo_test_iex) for rapid feedbaack during local development\n\n\n\n## Usage\n\n```elixir\n# {:ok, pid} = Surrealix.start_link(debug: [:trace]) ## for debugging!\n{:ok, pid} = Surrealix.start_link()\nSurrealix.signin(pid, %{user: \"root\", pass: \"root\"})\nSurrealix.use(pid, \"test\", \"test\")\nSurrealix.query(pid, \"SELECT * FROM person;\")\nSurrealix.query(pid, \"SELECT * FROM type::table($table);\", %{table: \"person\"})\n```\n\n```elixir\n## Example with live query callbacks\nSurrealix.live_query(pid, \"LIVE SELECT * FROM user;\", fn data, query_id -\u003e\n  IO.inspect({data, query_id}, label: \"callback\")\nend)\n\n## Example with live query with DIFF\nSurrealix.live_query(pid, \"LIVE SELECT DIFF FROM user;\", fn data, query_id -\u003e\n  IO.inspect({data, query_id}, label: \"callback\")\nend)\n\n\n# inspect currently registered live queries\nSurrealix.all_live_queries(pid)\n```\n\n## Handling reconnection\n\nTo 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.\n\nThis 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.\n\nLive 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.\n\n```elixir\n{:ok, pid} =\n    Surrealix.start(\n      on_auth: fn pid, _state -\u003e\n        IO.puts(\"PID: #{inspect(pid)}\")\n        Surrealix.signin(pid, %{user: \"root\", pass: \"root\"}) |\u003e IO.inspect(label: :signin)\n        Surrealix.use(pid, \"test\", \"test\") |\u003e IO.inspect(label: :use)\n      end\n    )\n\n# blocks until the `on_auth` callback is executed\nSurrealix.wait_until_auth_ready(pid)\n\n# now we can execute queries, that require auth\nSurrealix.live_query(pid, \"LIVE SELECT * FROM user;\", fn data, query_id -\u003e\n  IO.inspect({data, query_id}, label: \"callback\")\nend)\n\nSurrealix.live_query(pid, \"LIVE SELECT * FROM person;\", fn data, query_id -\u003e\n  IO.inspect({data, query_id}, label: \"callback\")\nend)\n```\n\n## Telemetry\nCurrently library publishes only 3 events:\n```elixir\nevents = [\n  [:surrealix, :exec_method, :start],\n  [:surrealix, :exec_method, :stop],\n  [:surrealix, :exec_method, :exception]\n]\n```\n\nIn the `meta` there is further information about the method name and the arguments, that were sent to SurrealDB server.\n\nAs example we provide a `Surrealix.Telemetry.Logger`, that logs those events to the console.\n\n```elixir\n## Configure basic logger telemetry\nSurrealix.Telemetry.Logger.setup()\n```\n\n## Configuration\n\n```elixir\n## in config.exs / runtime.exs file\nconfig :surrealix, backoff_max: 2000\nconfig :surrealix, backoff_step: 50\nconfig :surrealix, timeout: :infinity # default 5000\nconfig :surrealix, :conn,\n  hostname: \"0.0.0.0\",\n  port: 8000\n```\n\n\n## Installation\n\nIf [available in Hex](https://hex.pm/docs/publish), the package can be installed\nby adding `surrealix` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:surrealix, \"~\u003e 0.1\"}\n  ]\nend\n```\n\nDocumentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)\nand published on [HexDocs](https://hexdocs.pm). Once published, the docs can\nbe found at \u003chttps://hexdocs.pm/surrealix\u003e.\n\n## Aknowledgements\n\nCode 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.\n\n## Ref\n\n- [Websockex callbacks (Elixir)](https://github.com/Azolo/websockex/blob/master/lib/websockex.ex)\n- [Websocket Text Protocol](https://surrealdb.com/docs/integration/websocket/text)\n- [JS SDK for websockets](https://github.com/surrealdb/surrealdb.js/blob/main/src/strategies/websocket.ts)\n- [Source code for the Websocket Text Protocol docs](https://github.com/surrealdb/www.surrealdb.com/blob/main/app/templates/docs/integration/websocket/text.hbs)\n- [SurrealDB SQL statements](https://surrealdb.com/docs/surrealql/statements)\n- [SurrealDB functions](https://surrealdb.com/docs/surrealql/functions)\n\n\n## Support\n\n\u003cp\u003e\n  \u003ca href=\"https://quantor.consulting/?utm_source=github\u0026utm_campaign=surrealix\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/maxohq/sponsors/main/assets/quantor_consulting_logo.svg\"\n      alt=\"Sponsored by Quantor Consulting\" width=\"210\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## License\n\nThe lib is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxohq%2Fsurrealix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaxohq%2Fsurrealix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaxohq%2Fsurrealix/lists"}