surreal
surreal

View Source README

banner

surrealdb-erlang

 SurrealDB Erlang

SurrealDB driver for BEAM ecosystem

codecov license downloads tests
⚠️ You are currently viewing version 2 ⚠️

SurrealDB Erlang, also referred to as "surreal", is a robust and maintainable SurrealDB driver for BEAM ecosystem.

The library draws inspiration from the official surrealdb.js implementation.

index

 Index

installation

 Installation

SurrealDB Erlang is available on Hex.pm.

Add surreal to your list of dependencies in rebar.config file:

{deps, [{surreal, "2.1.0"}]}.

getting-started

 Getting Started

creating-a-connection

 Creating a Connection

You can establish a database connection with surreal:start_link/2 (or surreal:start_link/3).

Check out SurrealDB URI format described in the documentation.

{ok, Pid} = surreal:start_link("surrealdb://root:root@localhost:8000/test/test", my_connection).

Alternatively, you can use the specified connection name, my_connection, in place of Pid, as shown below:

{ok, Users} = surreal:select(my_connection, "users").

example-usage

 Example Usage

SurrealDB Erlang offers users a clean API, demonstrated below:

1> {ok, User} = surreal:create(Pid, "users:meppu", #{<<"score">> => 10}).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"score">> => 10}}
2> {ok, NewUser} = surreal:merge(Pid, "users:meppu", #{<<"new">> => <<"key">>}).
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"new">> => <<"key">>,
   %       <<"score">> => 10}}
3> [{ok, QueryResp}] = surreal:query(Pid, "SELECT * FROM users WHERE score = $score", #{<<"score">> => 10}).
   % [{ok,[#{<<"id">> => <<"users:meppu">>,<<"new">> => <<"key">>,
   %         <<"score">> => 10}]}]
4> {ok, RemovedUser} = surreal:delete(Pid, "users:meppu").
   % {ok,#{<<"id">> => <<"users:meppu">>,<<"new">> => <<"key">>,
   %       <<"score">> => 10}}
5> RemovedUser =:= NewUser.
   % true

with-supervisor

 With Supervisor

The recommended approach to initialise a SurrealDB connection is through a supervisor.

You can use surreal:child_spec/1 to create a child specification for your supervisor, as shown below:

ChildSpecs = [
    surreal:child_spec({"surrealdb://root:root@localhost:8000/test/test", db_conn, #{}})
],

additional-examples

 Additional Examples

See additional examples in examples/ folder.

documentation

 Documentation

For detailed documentation, please refer to HexDocs.

contributing

 Contributing

Feel free to report bugs and request features through GitHub Issues.

If you wish to submit a pull request, ensure that your code is well-formatted and easily comprehensible.

note-for-contributors

 Note for Contributors

Please send your pull requests to v2 branch instead of the main branch.

This helps us demostrate a stable version on the main branch while allowing for ongoing development and improvements on the v2 branch.

license

 License

SurrealDB Erlang is licensed under the MIT License.