Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/surrealdb/surrealdb.go
SurrealDB SDK for Golang
https://github.com/surrealdb/surrealdb.go
database database-connector golang golang-library golang-module iot-database realtime-database surreal surrealdb
Last synced: about 2 months ago
JSON representation
SurrealDB SDK for Golang
- Host: GitHub
- URL: https://github.com/surrealdb/surrealdb.go
- Owner: surrealdb
- License: apache-2.0
- Created: 2022-04-07T16:23:29.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-17T14:23:41.000Z (3 months ago)
- Last Synced: 2024-06-18T14:15:58.574Z (3 months ago)
- Topics: database, database-connector, golang, golang-library, golang-module, iot-database, realtime-database, surreal, surrealdb
- Language: Go
- Homepage: https://surrealdb.com
- Size: 126 KB
- Stars: 218
- Watchers: 19
- Forks: 58
- Open Issues: 39
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-go - surrealdb.go - SurrealDB Driver for Go. (Database Drivers / Relational Database Drivers)
- awesome-surreal - surrealdb.go - <a href="https://surrealdb.com#gh-dark-mode-only" target="_blank"><img src="/img/white/text.svg" height="12" alt="SurrealDB"></a> <a href="https://surrealdb.com#gh-light-mode-only" target="_blank"><img src="/img/black/text.svg" height="12" alt="SurrealDB"></a> official driver for Golang. (Client libraries)
README
The official SurrealDB SDK for Golang.
# surrealdb.go
The official SurrealDB SDK for Golang.
## Documentation
View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/golang).
## How to install
```sh
go get github.com/surrealdb/surrealdb.go
```
## Getting started
In the example below you can see how to connect to a remote instance of SurrealDB, authenticating with the database, and issuing queries for creating, updating, and selecting data from records.
> This example requires SurrealDB to be [installed](https://surrealdb.com/install) and running on port 8000.
```go
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)
}
}
```
### 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//` 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.
## 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.
## 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, and the library will automatically convert it to the correct type.
```go
// 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, and the library will automatically convert it to that type.
```go
// User struct is a test struct
data, err := surrealdb.SmartUnmarshal[testUser](s.db.Select(user[0].ID))
```