An unofficial SurrealDB driver for Nim.
Warning
This is a very early version - things are barely tested and are subject to change.
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:
You can install this library using Nimble:
nimble install surrealdb
or by adding it to your nimble
file:
requires "surrealdb >= 0.1.0"
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()
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
- 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