Unreal
Unofficial SurrealDB client for Elixir. Supports both WebSocket and HTTP connection.
⚠️ Unreal is well tested, but still may contain some bugs. Please report an issue if you got one.⚠️
Installation
Add unreal
to your list of dependencies in mix.exs
:
def deps do
[
{:unreal, "~> 0.2.2"}
]
end
Usage
Simple WebSocket Connection
config = %Unreal.Core.Config{
host: "ws://127.0.0.1:8000",
username: "root",
password: "root",
database: "test",
namespace: "test"
}
{:ok, pid} = Unreal.start_link(protocol: :websocket, config: config, name: :database)
Unreal.insert(pid, "users", "bob", %{age: 18, active: true})
Unreal.get(:database, "users")
With Supervisor
children = [
{Unreal,
protocol: :websocket,
config: %Unreal.Core.Config{
host: "ws://127.0.0.1:8000",
username: "root",
password: "root",
namespace: "test",
database: "test"
},
name: :database}
]
opts = [strategy: :one_for_one, name: Example.Supervisor]
Supervisor.start_link(children, opts)
Unreal.insert(:database, "users", "bob", %{age: 18, active: true})
With Tables
This macro allows you to use a table directly. Adds insert
, update
, get
, change
, modify
and delete
functions.
defmodule Users do
# name: the name of the connection
# table: table to use
use Unreal.Table, name: :database, table: "users"
end
Users.get("bob")
Queries
NOTE: Sending a variable to query is not supported in HTTP connection.
Unreal.query(:database, "SELECT * FROM users")
Unreal.query(:database, "SELECT * FROM users WHERE age > $age", %{
age: 30
})
Query Builders
This feature is inspired from Cirql and currently supports 5 operations.
alias Unreal.Writer
{query, params} =
Writer.Select.init()
|> Writer.Select.from("users")
|> Writer.Select.get([:id, :username, :age])
|> Writer.Select.where(age: {:ge, 18}, verified: true)
|> Writer.Select.build()
{:ok, result} = Unreal.query(:database, query, params)
Operators
There are some operators you can pass when you use query builders with set
or where
operations:
:le
: Check whether a value is less than or equal to another value:ge
: Check whether a value is greater than or equal to another value:lt
: Check whether a value is less than another value:gt
: Check whether a value is greater than another value:add
: Add value to existing value (ONLY FOR UPDATING):dec
: Substract value to existing value (ONLY FOR UPDATING):ne
: Check whether two values are not equal:any
: Check whether any value in a set is equal to a value:all
: Check whether all values in a set are equal to a value:in
: Checks whether a value is contained within another value:ex
: Checks whether a value is not contained within another value
# ...
|> Writer.Select.where(age: {:gt, 13}, verified: true)
# ...
As you can see, if we pass the value directly (like verified: true
) it will generate it as equals operation.
And if you want to pass a custom operator, you can change first value of the tuple to anything you want.
# ...
|> Writer.Select.where(thing: {"==", 26}) # Strict Equality
# ...
Ways to Use Order of Preference
-
Default functions like
insert
,update
,delete
etc. are the simplest way to use. -
For more flexible queries, use built-in query builders.
-
If query builders are not enough, and you need to run something complex, use
query
function.# NOTE: Query builders are flexible enough for this query. # This is just an example. # Bad, allows users to inject SurrealQL commands. Unreal.query(pid, "SELECT token FROM users WHERE password = #{password}") # Good and safe. Unreal.query(pid, "SELECT token FROM users WHERE password = $pass", %{pass: password})
Documentation
Documentation is avaible at HexDocs.
Contributing
- Report bugs or request features here.
- Always use
mix format
before sending a pull request.
License
Unreal is licensed under the MIT License.