surrealdb

README

surrealdb.go

The official SurrealDB library for Golang.

Documentation

Index

• func Unmarshal(data any, v any) error
• type DB
  • func New(url string) (*DB, error)
  • func (self *DB) Authenticate(token string) (any, error)
  • func (self *DB) Change(what string, data any) (any, error)
  • func (self *DB) Close()
  • func (self *DB) Create(thing string, data any) (any, error)
  • func (self *DB) Delete(what string) (any, error)
  • func (self *DB) Info() (any, error)
  • func (self *DB) Invalidate() (any, error)
  • func (self *DB) Kill(query string) (any, error)
  • func (self *DB) Let(key string, val any) (any, error)
  • func (self *DB) Live(table string) (any, error)
  • func (self *DB) Modify(what string, data any) (any, error)
  • func (self *DB) Query(sql string, vars any) (any, error)
  • func (self *DB) Select(what string) (any, error)
  • func (self *DB) Signin(vars any) (any, error)
  • func (self *DB) Signup(vars any) (any, error)
  • func (self *DB) Update(what string, data any) (any, error)
  • func (self *DB) Use(ns string, db string) (any, error)
• type PermissionError
  • func (self PermissionError) Error() string
• type RPCError
  • func (r *RPCError) Error() string
• type RPCNotification
• type RPCRequest
• type RPCResponse
• type WS
  • func NewWebsocket(url string) (*WS, error)
  • func (self *WS) Close() error
  • func (self *WS) Once(id, method string) (<-chan any, <-chan error)
  • func (self *WS) Send(id string, method string, params []any)
  • func (self *WS) When(id, method string) (<-chan any, <-chan error)

Examples

• DB.Create
• DB.Delete
• DB.Select
• DB.Update
• New

Functions

func Unmarshal

func Unmarshal(data any, v any) error

Unmarshal unmarshals a SurrealDB response into a struct.

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB is a client for the SurrealDB database that holds are websocket connection.

func New

func New(url string) (*DB, error)

New Creates a new DB instance given a WebSocket URL.

Example

an example test for creating a new entry in surrealdb

db, err := surrealdb.New("ws://localhost:8000/rpc")

if err != nil {
	panic(err)
}

defer db.Close()

func (*DB) Authenticate

func (self *DB) Authenticate(token string) (any, error)

func (*DB) Change

func (self *DB) Change(what string, data any) (any, error)

Change a table or record in the database like a PATCH request.

func (*DB) Close

func (self *DB) Close()

Close closes the underlying WebSocket connection.

func (*DB) Create

func (self *DB) Create(thing string, data any) (any, error)

Creates a table or record in the database like a POST request.

Example

db, err := surrealdb.New("ws://localhost:8000/rpc")

if err != nil {
	panic(err)
}

defer db.Close()

signin, err := db.Signin(map[string]interface{}{
	"user": "root",
	"pass": "root",
})

if err != nil {
	panic(err)
}

_, err = db.Use("test", "test")

if err != nil || signin == nil {
	panic(err)
}

userMap, err := db.Create("users", map[string]interface{}{
	"username": "john",
	"password": "123",
})

if err != nil || userMap == nil {
	panic(err)
}

userData, err := db.Create("users", testUser{
	Username: "johnny",
	Password: "123",
})

var user testUser
err = surrealdb.Unmarshal(userData, &user)
if err != nil {
	panic(err)
}

fmt.Println(user.Username)

Output:

johnny

func (*DB) Delete

func (self *DB) Delete(what string) (any, error)

Delete a table or a row from the database like a DELETE request.

Example

db, err := surrealdb.New("ws://localhost:8000/rpc")
if err != nil {
	panic(err)
}
defer db.Close()

_, err = db.Signin(map[string]interface{}{
	"user": "root",
	"pass": "root",
})

if err != nil {
	panic(err)
}

_, err = db.Use("test", "test")

if err != nil {
	panic(err)
}

userData, err := db.Create("users", testUser{
	Username: "johnny",
	Password: "123",
})

// unmarshal the data into a user struct
var user testUser
err = surrealdb.Unmarshal(userData, &user)
if err != nil {
	panic(err)
}

// Delete the users... TODO: should let users specify a selector other than '*'
_, err = db.Delete("users")

if err != nil {
	panic(err)
}

func (*DB) Info

func (self *DB) Info() (any, error)

func (*DB) Invalidate

func (self *DB) Invalidate() (any, error)

func (*DB) Kill

func (self *DB) Kill(query string) (any, error)

func (*DB) Let

func (self *DB) Let(key string, val any) (any, error)

func (*DB) Live

func (self *DB) Live(table string) (any, error)

func (*DB) Modify

func (self *DB) Modify(what string, data any) (any, error)

Modify applies a series of JSONPatches to a table or record.

func (*DB) Query

func (self *DB) Query(sql string, vars any) (any, error)

Query is a convenient method for sending a query to the database.

func (*DB) Select

func (self *DB) Select(what string) (any, error)

Select a table or record from the database.

Example

db, err := surrealdb.New("ws://localhost:8000/rpc")

if err != nil {
	panic(err)
}

defer db.Close()

_, err = db.Signin(map[string]interface{}{
	"user": "root",
	"pass": "root",
})

if err != nil {
	panic(err)
}

_, err = db.Use("test", "test")

if err != nil {
	panic(err)
}

_, err = db.Create("users", testUser{
	Username: "johnnyjohn",
	Password: "123",
})

userData, err := db.Select("users") // TODO: should let users specify a selector other than '*'

// unmarshal the data into a user slice
users := []testUser{}
err = surrealdb.Unmarshal(userData, &users)
if err != nil {
	panic(err)
}

for _, user := range users {
	if user.Username == "johnnyjohn" {
		fmt.Println(user.Username)
		break
	}
}

Output:

johnnyjohn

func (*DB) Signin

func (self *DB) Signin(vars any) (any, error)

Signin is a helper method for signing in a user.

func (*DB) Signup

func (self *DB) Signup(vars any) (any, error)

SignUp is a helper method for signing up a new user.

func (*DB) Update

func (self *DB) Update(what string, data any) (any, error)

Update a table or record in the database like a PUT request.

Example

db, err := surrealdb.New("ws://localhost:8000/rpc")
if err != nil {
	panic(err)
}
defer db.Close()

_, err = db.Signin(map[string]interface{}{
	"user": "root",
	"pass": "root",
})

if err != nil {
	panic(err)
}

_, err = db.Use("test", "test")

if err != nil {
	panic(err)
}

userData, err := db.Create("users", testUser{
	Username: "johnny",
	Password: "123",
})

// unmarshal the data into a user struct
var user testUser
err = surrealdb.Unmarshal(userData, &user)
if err != nil {
	panic(err)
}

user.Password = "456"

// Update the user
userData, err = db.Update("users", user)

if err != nil {
	panic(err)
}

// unmarshal the data into a user struct
var updatedUser []testUser
err = surrealdb.Unmarshal(userData, &updatedUser)

if err != nil {
	panic(err)
}

// TODO: check if this updates only the user with the same ID or all users
fmt.Println(updatedUser[0].Password)

Output:

456

func (*DB) Use

func (self *DB) Use(ns string, db string) (any, error)

Use is a method to select the namespace and table to use.

type PermissionError

type PermissionError struct {
	// contains filtered or unexported fields
}

func (PermissionError) Error

func (self PermissionError) Error() string

type RPCError

type RPCError struct {
	Code    int    `json:"code" msgpack:"code"`
	Message string `json:"message,omitempty" msgpack:"message,omitempty"`
}

RPCError represents a JSON-RPC error

func (*RPCError) Error

func (r *RPCError) Error() string

type RPCNotification

type RPCNotification struct {
	ID     any    `json:"id" msgpack:"id"`
	Method string `json:"method,omitempty" msgpack:"method,omitempty"`
	Params []any  `json:"params,omitempty" msgpack:"params,omitempty"`
}

RPCNotification represents an outgoing JSON-RPC notification

type RPCRequest

type RPCRequest struct {
	ID     any    `json:"id" msgpack:"id"`
	Async  bool   `json:"async,omitempty" msgpack:"async,omitempty"`
	Method string `json:"method,omitempty" msgpack:"method,omitempty"`
	Params []any  `json:"params,omitempty" msgpack:"params,omitempty"`
}

RPCRequest represents an incoming JSON-RPC request

type RPCResponse

type RPCResponse struct {
	ID     any       `json:"id" msgpack:"id"`
	Error  *RPCError `json:"error,omitempty" msgpack:"error,omitempty"`
	Result any       `json:"result,omitempty" msgpack:"result,omitempty"`
}

RPCResponse represents an outgoing JSON-RPC response

type WS

type WS struct {
	// contains filtered or unexported fields
}

func NewWebsocket

func NewWebsocket(url string) (*WS, error)

func (*WS) Close

func (self *WS) Close() error

func (*WS) Once

func (self *WS) Once(id, method string) (<-chan any, <-chan error)

func (*WS) Send

func (self *WS) Send(id string, method string, params []any)

func (*WS) When

func (self *WS) When(id, method string) (<-chan any, <-chan error)