# 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.1"}

## Usage

### Simple WebSocket Connection

config = %Unreal.Core.Config{
  host: "ws://",
  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 = [
    protocol: :websocket,
    config: %Unreal.Core.Config{
      host: "ws://",
      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"


### 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.from("users")
  |> Writer.Select.get([:id, :username, :age])
  |> Writer.Select.where(age: {:>, 18}, verified: true)

{:ok, result} = Unreal.query(:database, query, params)

### 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

- Please don't send any pull request to main branch.
- Report bugs or request features [here](
- Always use `mix format` before sending a pull request.

## License

Unreal is licensed under the MIT License.