surrealdb

README

surrealdb.go

The non-official SurrealDB library for Golang.

Getting Started

For instructions on how to follow SurrealDB, follow Installation Guide

Installation

go get github.com/surrealdb/surrealdb.go

Usage

package main
import (
	"github.com/surrealdb/surrealdb.go"

)

type User struct {
	ID      string `json:"id,omitempty"`
	Name    string `json:"name"`
	Surname string `json:"surname"`
}

func main() {
	// Connect to SurrealDB
	db, err := surrealdb.New("ws://localhost:8000/rpc")
	if err != nil {
		panic(err)
	}

	authData := &surrealdb.Auth{
		Database:  "test",
		Namespace: "test",
		Username:  "root",
		Password:  "root",
	}
	if _, err = db.Signin(authData); err != nil {
		panic(err)
	}

	if _, err = db.Use("test", "test"); err != nil {
		panic(err)
	}

	// Define user struct
	user := User{
		Name:    "John",
		Surname: "Doe",
	}

	// Insert user
	data, err := db.Create("user", user)
	if err != nil {
		panic(err)
	}

	// Unmarshal data
	createdUser := make([]User, 1)
	err = surrealdb.Unmarshal(data, &createdUser)
	if err != nil {
		panic(err)
	}

	// Get user by ID
	data, err = db.Select(createdUser[0].ID)
	if err != nil {
		panic(err)
	}

	// Unmarshal data
	selectedUser := new(User)
	err = surrealdb.Unmarshal(data, &selectedUser)
	if err != nil {
		panic(err)
	}

	// Change part/parts of user
	changes := map[string]string{"name": "Jane"}

	// Update user
	if _, err = db.Update(selectedUser.ID, changes); err != nil {
		panic(err)
	}

	if _, err = db.Query("SELECT * FROM $record", map[string]interface{}{
		"record": createdUser[0].ID,
	}); err != nil {
		panic(err)
	}

	// Delete user by ID
	if _, err = db.Delete(selectedUser.ID); err != nil {
		panic(err)
	}
}

• Step 1: Create a file called main.go and paste the above code
• Step 2: Run the command go mod init github.com/<github-username>/<project-name> to create a go.mod file
• Step 3: Run the command go mod tidy to download surreal db
• Step 4: Run go run main.go to run the application.

Documentation

Full documentation is available at surrealdb doc

## Building

You can run the Makefile helper to run and build the project

make build
make test
make lint

You also need to be running SurrealDB alongside the tests. We recommend using the nightly build, as development may rely on the latest functionality.

Helper functions

Smart Marshal

SurrealDB Go library supports smart marshal. It means that you can use any type of data as a value in your struct. SurrealDB Go library will automatically convert it to the correct type.

// Recommended to use with SmartUnmarshal SmartMarshal
// User struct is a test struct
user, err := surrealdb.SmartUnmarshal[testUser](surrealdb.SmartMarshal(s.db.Create, user[0]))

// Can be used without SmartUnmarshal
data, err := surrealdb.SmartMarshal(s.db.Create, user[0])

Smart Unmarshal

SurrealDB Go library supports smart unmarshal. It means that you can unmarshal any type of data to the generic type provided. SurrealDB Go library will automatically convert it to that type.

// User struct is a test struct
data, err := surrealdb.SmartUnmarshal[testUser](s.db.Select(user[0].ID))

Documentation

Index

• type Auth
• type DB
  • func New(url string, connection conn.Connection) (*DB, error)
  • func (db *DB) Authenticate(token string) (interface{}, error)
  • func (db *DB) Close() error
  • func (db *DB) Create(thing string, data interface{}) (interface{}, error)
  • func (db *DB) Delete(what string) (interface{}, error)
  • func (db *DB) Info() (interface{}, error)
  • func (db *DB) Insert(what string, data interface{}) (interface{}, error)
  • func (db *DB) Invalidate() (interface{}, error)
  • func (db *DB) Kill(liveQueryID string) (interface{}, error)
  • func (db *DB) Let(key string, val interface{}) (interface{}, error)
  • func (db *DB) Live(table string, diff bool) (string, error)
  • func (db *DB) LiveNotifications(liveQueryID string) (chan model.Notification, error)
  • func (db *DB) Merge(what string, data interface{}) (interface{}, error)
  • func (db *DB) Patch(what string, data []Patch) (interface{}, error)
  • func (db *DB) Query(sql string, vars interface{}) (interface{}, error)
  • func (db *DB) Select(what string) (interface{}, error)
  • func (db *DB) Signin(authData *Auth) (interface{}, error)
  • func (db *DB) Signup(authData *Auth) (interface{}, error)
  • func (db *DB) Start() error
  • func (db *DB) Update(what string, data interface{}) (interface{}, error)
  • func (db *DB) Use(ns, database string) (interface{}, error)
• type Patch

Types

type Auth

type Auth struct {
	Namespace string `json:"NS,omitempty"`
	Database  string `json:"DB,omitempty"`
	Scope     string `json:"SC,omitempty"`
	Username  string `json:"user,omitempty"`
	Password  string `json:"pass,omitempty"`
}

Auth is a struct that holds surrealdb auth data for login.

type DB

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

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

func New

func New(url string, connection conn.Connection) (*DB, error)

New creates a new SurrealDB client.

func (*DB) Authenticate

func (db *DB) Authenticate(token string) (interface{}, error)

func (*DB) Close

func (db *DB) Close() error

Close closes the underlying WebSocket connection.

func (*DB) Create

func (db *DB) Create(thing string, data interface{}) (interface{}, error)

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

func (*DB) Delete

func (db *DB) Delete(what string) (interface{}, error)

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

func (*DB) Info

func (db *DB) Info() (interface{}, error)

func (*DB) Insert

func (db *DB) Insert(what string, data interface{}) (interface{}, error)

Insert a table or a row from the database like a POST request.

func (*DB) Invalidate

func (db *DB) Invalidate() (interface{}, error)

func (*DB) Kill

func (db *DB) Kill(liveQueryID string) (interface{}, error)

func (*DB) Let

func (db *DB) Let(key string, val interface{}) (interface{}, error)

func (*DB) Live

func (db *DB) Live(table string, diff bool) (string, error)

func (*DB) LiveNotifications

func (db *DB) LiveNotifications(liveQueryID string) (chan model.Notification, error)

LiveNotifications returns a channel for live query.

func (*DB) Merge

func (db *DB) Merge(what string, data interface{}) (interface{}, error)

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

func (*DB) Patch

func (db *DB) Patch(what string, data []Patch) (interface{}, error)

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

func (*DB) Query

func (db *DB) Query(sql string, vars interface{}) (interface{}, error)

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

func (*DB) Select

func (db *DB) Select(what string) (interface{}, error)

Select a table or record from the database.

func (*DB) Signin

func (db *DB) Signin(authData *Auth) (interface{}, error)

Signin is a helper method for signing in a user.

func (*DB) Signup

func (db *DB) Signup(authData *Auth) (interface{}, error)

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

func (*DB) Start

func (db *DB) Start() error

func (*DB) Update

func (db *DB) Update(what string, data interface{}) (interface{}, error)

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

func (*DB) Use

func (db *DB) Use(ns, database string) (interface{}, error)

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

type Patch

type Patch struct {
	Value any    `json:"value"`
	Op    string `json:"op"`
	Path  string `json:"path"`
}