ProductPromotion
Logo

Go.Lang

made by https://0x3d.site

GitHub - surrealdb/surrealdb.go: SurrealDB SDK for Golang
SurrealDB SDK for Golang. Contribute to surrealdb/surrealdb.go development by creating an account on GitHub.
Visit Site

GitHub - surrealdb/surrealdb.go: SurrealDB SDK for Golang

GitHub - surrealdb/surrealdb.go: SurrealDB SDK for Golang

surrealdb.go

The official SurrealDB SDK for Golang.

Documentation

View the SDK documentation here.

How to install

go get github.com/surrealdb/surrealdb.go

Getting started

In the example provided below, we are going to connect and authenticate on a SurrealDB server, set the namespace and make several data manipulation requests.

This example requires SurrealDB to be installed and running on port 8000.

package main

import (
	"fmt"
	surrealdb "github.com/surrealdb/surrealdb.go"
	"github.com/surrealdb/surrealdb.go/pkg/models"
)

type Person struct {
	ID      	*models.RecordID `json:"id,omitempty"`
	Name    	string `json:"name"`
	Surname 	string `json:"surname"`
	Location 	models.GeometryPoint `json:"location"`
}

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

	// Set the namespace and database
	if err = db.Use("testNS", "testDB"); err != nil {
		panic(err)
	}

	// Sign in to authentication `db`
	authData := &surrealdb.Auth{
		Username: "root", // use your setup username
		Password: "root", // use your setup password
	}
	token, err := db.SignIn(authData)
	if err != nil {
		panic(err)
	}

	// Check token validity. This is not necessary if you called `SignIn` before. This authenticates the `db` instance too if sign in was
	// not previously called
	if err := db.Authenticate(token); err != nil {
		panic(err)
	}

	// And we can later on invalidate the token if desired
	defer func(token string) {
		if err := db.Invalidate(); err != nil {
			panic(err)
		}
	}(token)

	// Create an entry
	person1, err := surrealdb.Create[Person](db, models.Table("persons"), map[interface{}]interface{}{
		"Name":     "John",
		"Surname":  "Doe",
		"Location": models.NewGeometryPoint(-0.11, 22.00),
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Created person with a map: %+v\n", person1)

	// Or use structs
	person2, err := surrealdb.Create[Person](db, models.Table("persons"), Person{
		Name:     "John",
		Surname:  "Doe",
		Location: models.NewGeometryPoint(-0.11, 22.00),
	})
	if err != nil {
		panic(err)
	}
	fmt.Printf("Created person with a struvt: %+v\n", person2)

	// Get entry by Record ID
	person, err := surrealdb.Select[Person, models.RecordID](db, *person1.ID)
	if err != nil {
		panic(err)
	}
	fmt.Printf("Selected a person by record id: %+v\n", person)

	// Or retrieve the entire table
	persons, err := surrealdb.Select[[]Person, models.Table](db, models.Table("persons"))
	if err != nil {
		panic(err)
	}
	fmt.Printf("Selected all in persons table: %+v\n", persons)

	// Delete an entry by ID
	if err = surrealdb.Delete[models.RecordID](db, *person2.ID); err != nil {
		panic(err)
	}

	// Delete all entries
	if err = surrealdb.Delete[models.Table](db, models.Table("persons")); err != nil {
		panic(err)
	}

	// Confirm empty table
	persons, err = surrealdb.Select[[]Person](db, models.Table("persons"))
	if err != nil {
		panic(err)
	}
	fmt.Printf("No Selected person: %+v\n", persons)
}

Doing it your way

All Data manipulation methods are handled by an undelying send function. This function is exposed via db.Send function if you want to create requests yourself but limited to a selected set of methods. Theses methods are:

  • select
  • create
  • insert
  • upsert
  • update
  • patch
  • delete
  • query
type UserSelectResult struct {
	Result []Users
}

var res UserSelectResult
// or var res surrealdb.Result[[]Users]

err := db.Send(&res, "query", user.ID)
if err != nil {
	panic(err)
}
	

Instructions for running the example

  • In a new folder, create a file called main.go and paste the above code
  • Run go mod init github.com/<github-username>/<project-name> to initialise a go.mod file
  • Run go mod tidy to download the surrealdb.go dependency
  • Run go run main.go to run the example.

Connection Engines

There are 2 different connection engines you can use to connect to SurrealDb backend. You can do so via Websocket or through HTTP connections

Via Websocket

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

or for a secure connection

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

Via HTTP

There are some functions that are not available on RPC when using HTTP but on Websocket. All these except the "live" endpoint are effectively implemented in the HTTP library and provides the same result as though it is natively available on HTTP. While using the HTTP connection engine, note that live queries will still use a websocket connection if the backend supports it

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

or for a secure connection

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

Data Models

This package facilitates communication between client and the backend service using the Concise Binary Object Representation (CBOR) format. It streamlines data serialization and deserialization while ensuring efficient and lightweight communication. The library also provides custom models tailored to specific Data models recognised by SurrealDb, which cannot be covered by idiomatic go, enabling seamless interaction between the client and the backend.

See the documetation on data models on support data types

CBOR Type Go Representation Example
Null nil var x interface{} = nil
None surrealdb.None map[string]interface{}{"customer": surrealdb.None}
Boolean bool true, false
Array []interface{} []MyStruct{item1, item2}
Date/Time time.Time time.Now()
Duration time.Duration time.Duration(8821356)
UUID (string representation) surrealdb.UUID(string) surrealdb.UUID("123e4567-e89b-12d3-a456-426614174000")
UUID (binary representation) surrealdb.UUIDBin([]bytes) surrealdb.UUIDBin([]byte{0x01, 0x02, ...})`
Integer uint, uint64, int, int64 42, uint64(100000), -42, int64(-100000)
Floating Point float32, float64 3.14, float64(2.71828)
Byte String, Binary Encoded Data []byte []byte{0x01, 0x02}
Text String string "Hello, World!"
Map map[interface{}]interface{} map[string]float64{"one": 1.0}
Table name surrealdb.Table(name) surrealdb.Table("users")
Record ID surrealdb.RecordID{Table: string, ID: interface{}} surrealdb.RecordID{Table: "customers", ID: 1}, surrealdb.NewRecordID("customers", 1)
Geometry Point surrealdb.GeometryPoint{Latitude: float64, Longitude: float64} surrealdb.GeometryPoint{Latitude: 11.11, Longitude: 22.22
Geometry Line surrealdb.GeometryLine{GeometricPoint1, GeometricPoint2,... }
Geometry Polygon surrealdb.GeometryPolygon{GeometryLine1, GeometryLine2,... }
Geometry Multipoint surrealdb.GeometryMultiPoint{GeometryPoint1, GeometryPoint2,... }
Geometry MultiLine surrealdb.GeometryMultiLine{GeometryLine1, GeometryLine2,... }
Geometry MultiPolygon surrealdb.GeometryMultiPolygon{GeometryPolygon1, GeometryPolygon2,... }
Geometry Collection surrealdb.GeometryMultiPolygon{GeometryPolygon1, GeometryLine2, GeometryPoint3, GeometryMultiPoint4,... }

Helper Types

surrealdb.O

For some methods like create, insert, update, you can pass a map instead of an struct value. An example:

person, err := surrealdb.Create[Person](db, models.Table("persons"), map[interface{}]interface{}{
	"Name":     "John",
	"Surname":  "Doe",
	"Location": models.NewGeometryPoint(-0.11, 22.00),
})

This can be simplified to:

person, err := surrealdb.Create[Person](db, models.Table("persons"), surrealdb.O{
	"Name":     "John",
	"Surname":  "Doe",
	"Location": models.NewGeometryPoint(-0.11, 22.00),
})

Where surrealdb.O is defined below. There is no special advantage in using this other than simplicity/legibility.

type surrealdb.O map[interface{}]interface{}

surrealdb.Result[T]

This is useful for the Send function where T is the expected response type for a request. An example:

var res surrealdb.Result[[]Users]
err := db.Send(&res, "select", model.Table("users"))
if err != nil {
	panic(err)
}
fmt.Printf("users: %+v\n", users.R)

Contributing

You can run the Makefile commands 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.

Articles
to learn more about the golang concepts.

Resources
which are currently available to browse on.

mail [email protected] to add your project or resources here ๐Ÿ”ฅ.

FAQ's
to know more about the topic.

mail [email protected] to add your project or resources here ๐Ÿ”ฅ.

Queries
or most google FAQ's about GoLang.

mail [email protected] to add more queries here ๐Ÿ”.

More Sites
to check out once you're finished browsing here.

0x3d
https://www.0x3d.site/
0x3d is designed for aggregating information.
NodeJS
https://nodejs.0x3d.site/
NodeJS Online Directory
Cross Platform
https://cross-platform.0x3d.site/
Cross Platform Online Directory
Open Source
https://open-source.0x3d.site/
Open Source Online Directory
Analytics
https://analytics.0x3d.site/
Analytics Online Directory
JavaScript
https://javascript.0x3d.site/
JavaScript Online Directory
GoLang
https://golang.0x3d.site/
GoLang Online Directory
Python
https://python.0x3d.site/
Python Online Directory
Swift
https://swift.0x3d.site/
Swift Online Directory
Rust
https://rust.0x3d.site/
Rust Online Directory
Scala
https://scala.0x3d.site/
Scala Online Directory
Ruby
https://ruby.0x3d.site/
Ruby Online Directory
Clojure
https://clojure.0x3d.site/
Clojure Online Directory
Elixir
https://elixir.0x3d.site/
Elixir Online Directory
Elm
https://elm.0x3d.site/
Elm Online Directory
Lua
https://lua.0x3d.site/
Lua Online Directory
C Programming
https://c-programming.0x3d.site/
C Programming Online Directory
C++ Programming
https://cpp-programming.0x3d.site/
C++ Programming Online Directory
R Programming
https://r-programming.0x3d.site/
R Programming Online Directory
Perl
https://perl.0x3d.site/
Perl Online Directory
Java
https://java.0x3d.site/
Java Online Directory
Kotlin
https://kotlin.0x3d.site/
Kotlin Online Directory
PHP
https://php.0x3d.site/
PHP Online Directory
React JS
https://react.0x3d.site/
React JS Online Directory
Angular
https://angular.0x3d.site/
Angular JS Online Directory