surrealdb

SurrealDB driver for Nim


Keywords
surrealdb, database, surrealql, driver, sql, nosql, websocket, hacktoberfest, nim, no-sql
License
MIT
Install
nimble install surrealdb

Documentation

SurrealDB.nim

An unofficial SurrealDB driver for Nim.

Warning

This is a very early version - things are barely tested and are subject to change.

⚒️ Current development status

Currently, the CBOR protocol is being implemented, which will lead to:

  • Improved performance
  • Support for easier ways to specify query parameters with specific types of values
  • Support for receiving responses that contain type information

This will change the API of the library drastically.

You can follow the development of this library on:

Insstalllation

You can install this library using Nimble:

nimble install surrealdb

or by adding it to your nimble file:

requires "surrealdb >= 0.1.0"

▶️ Usage example

import surrealdb

proc main() {.async.} =
    # Connect to SurrealDB
    let surreal = await newSurrealDbConnection(ws://localhost:1234/rpc)

    # Disconnect from SurrealDB afterwards
    defer: surreal.disconnect()

    # Switch to the test database
    let ns = "test"
    let db = "test"
    let useResponse = await surreal.use(ns, db)
    # Responses allow to call `.isOk` to check if the request was successful
    assert useResponse.isOk

    # Sign in as root user
    let signinResponse = await surreal.signin("rootuser", "somepassword")
    if not signinResponse.isOk:
        # You can also access the error message if the database returned an error
        echo "Signin error: ", signinResponse.error.message
        quit(1)

    # Query the database
    # The `surql` string literal creates a distinct string of type `SurQL`
    let queryResponse = await surreal.query(surql"SELECT * FROM users")

    if queryResponse.isOk:
        # Print out the result
        # The `ok` field contains the result of the query
        # The results is a JSON array with a result-per-query
        echo "Query result: ", queryResponse.ok[0]["result"]

    # The `rc` string literal creates a new RecordID object
    let selectResponse = await surreal.select(rc"users:12345")

    # The `tb` string literal creates a new TableName object
    let tableResponse = await surreal.select(tb"users")

waitFor main()

✅ Support for RPC JSON methods

This is a list of methods implemented methods that take JsonNode or strings as inputs and return JsonNode as output. No smart deserialization etc:

  • use method
  • info method
  • version method
  • signup method
  • signin method
  • authenticate method
  • invalidate method
  • let method
  • unset method
  • query method
  • select method
  • create method
  • insert method
  • update method
  • upsert method
  • relate method
  • merge method
  • delete method
  • run method

The following methods will be implemented after the CBOR-based RPC is implemented:

  • live method
  • kill method
  • patch method
  • qraphql method
  • queryRaw method

⏳ Next steps

  • Use CBOR instead of JSON for RPC requests (in progress)
  • Automatic marshalling of SurrealDB types to/from Nim types
  • Various helpers for dealing with returned data
  • Automated testing via GitHub Actions that run SurrealDB in docker containers