From f83cef6dc2989d7976f801269ea7777cb74757b9 Mon Sep 17 00:00:00 2001 From: Tobie Morgan Hitchcock Date: Sun, 12 May 2024 11:47:02 +0100 Subject: [PATCH] Update README --- README.md | 78 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 29ca39b..736af0e 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,60 @@ -# surrealdb.go +
+ +

+ +   + +

+ +

The official SurrealDB SDK for Golang.

+ +
+ +

+ +   + +   + +   + +

+ +

+ +   + +   + +   + +

-The official SurrealDB library for Golang. +# surrealdb.go -[![](https://img.shields.io/badge/status-beta-ff00bb.svg?style=flat-square)](https://github.com/surrealdb/surrealdb.go) -[![](https://img.shields.io/badge/docs-view-44cc11.svg?style=flat-square)](https://surrealdb.com/docs/integration/libraries/golang) -[![Go Reference](https://pkg.go.dev/badge/github.com/surrealdb/surrealdb.go.svg)](https://pkg.go.dev/github.com/surrealdb/surrealdb.go) -[![Go Report Card](https://goreportcard.com/badge/github.com/surrealdb/surrealdb.go)](https://goreportcard.com/report/github.com/surrealdb/surrealdb.go) -[![](https://img.shields.io/badge/license-Apache_License_2.0-00bfff.svg?style=flat-square)](https://github.com/surrealdb/surrealdb.go) -[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) +The official SurrealDB SDK for Golang. -## Getting Started +## Documentation -For instructions on how to follow SurrealDB, follow [Installation Guide](https://surrealdb.com/docs/installation) +View the SDK documentation [here](https://surrealdb.com/docs/integration/libraries/golang). -### Installation +## How to install -```bash +```sh go get github.com/surrealdb/surrealdb.go ``` -### Usage +## 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 { @@ -108,18 +137,16 @@ func main() { } ``` -* Step 1: Create a file called `main.go` and paste the above code -* Step 2: Run the command `go mod init github.com//` 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. +### Instructions for running the example -# Documentation +- 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. -Full documentation is available at [surrealdb doc](https://surrealdb.com/docs/integration/libraries/golang) +## Contributing -## Building - -You can run the Makefile helper to run and build the project +You can run the Makefile commands to run and build the project ``` make build @@ -130,14 +157,13 @@ 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. ```go -// Recommended to use with SmartUnmarshal SmartMarshal // User struct is a test struct user, err := surrealdb.SmartUnmarshal[testUser](surrealdb.SmartMarshal(s.db.Create, user[0])) @@ -150,10 +176,8 @@ data, err := surrealdb.SmartMarshal(s.db.Create, user[0]) 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. ```go - // User struct is a test struct data, err := surrealdb.SmartUnmarshal[testUser](s.db.Select(user[0].ID)) - ```