This page shows how to add the Go SDK to a module and which packages to import. It also lists the versions of Go and SurrealDB that the SDK works with.
Install the SDK
Add the SDK to your module with go get:
go get github.com/surrealdb/surrealdb.go/v2The module path ends in /v2. Without it, go get installs the latest 1.x release, which is a different module. To install a specific release, add the version:
go get github.com/surrealdb/surrealdb.go/v2@v2.0.1To check which version of the SDK a module uses, run this command:
go list -m github.com/surrealdb/surrealdb.go/v2Import the SDK into your project
Import the surrealdb package and its models package:
import (
surrealdb "github.com/surrealdb/surrealdb.go/v2"
"github.com/surrealdb/surrealdb.go/v2/pkg/models"
)The surrealdb package contains the client, the query and CRUD functions, the options and the errors. The models package contains the value types, such as RecordID, Table and PlainDate.
Other packages in the module cover more specialised needs:
| Package | What it contains |
|---|---|
github.com/surrealdb/surrealdb.go/v2/pkg/connection | The connection configuration, live query notifications, and the error types that the surrealdb package re-exports. |
github.com/surrealdb/surrealdb.go/v2/pkg/connection/gorillaws, .../gws, .../http | The WebSocket and HTTP connections, for a custom connection. |
github.com/surrealdb/surrealdb.go/v2/pkg/constants | Sentinel errors, such as ErrSessionClosed. |
github.com/surrealdb/surrealdb.go/v2/contrib/surrealql | The query builder. |
github.com/surrealdb/surrealdb.go/v2/contrib/rews | A reconnecting WebSocket connection with its own retry strategies. |
github.com/surrealdb/surrealdb.go/v2/memory | The Agent Memory client. |
The packages under contrib/ are outside the backward compatibility guarantee of the SDK. Their API can change in a minor release.
Requirements
Go
1.24or laterSurrealDB
3.3.0or later, before5.0.0. SurrealDB 4.0 is the recommended version. The kinds that it adds, such as sized numbers, dates and regexes, work only with SurrealDB 4.0. See Value types.
The SDK does not check the server version unless you ask it to. To make the connection fail on a server outside the supported range, pass WithVersionCheck(true).
Next steps
Getting started for a complete working example
Connecting to SurrealDB for connection options and protocols
Authentication for signing in and managing tokens
Migrating to Go SDK 2.x for upgrading a project from version 1