README
¶
surrealdb.go
The official SurrealDB library for Golang.
Getting Started
For instructions on how to follow SurrealDB, follow Installation Guide
Installation
go get github.com/geekendev/surrealdb.go
Usage
package main
import (
"github.com/geekendev/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.goand 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 tidyto download surreal db - Step 4: Run
go run main.goto 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 (db *DB) Authenticate(token string) (interface{}, error)
- func (db *DB) Close()
- 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) Update(what string, data interface{}) (interface{}, error)
- func (db *DB) Use(ns, database string) (interface{}, error)
- type Patch
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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) Invalidate ¶
func (*DB) LiveNotifications ¶
func (db *DB) LiveNotifications(liveQueryID string) (chan model.Notification, error)
LiveNotifications returns a channel for live query.
Source Files
Directories