Skip to content

Go

Installation

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.

Add the SDK to your module with go get:

go get github.com/surrealdb/surrealdb.go/v2

The 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.1

To check which version of the SDK a module uses, run this command:

go list -m github.com/surrealdb/surrealdb.go/v2

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:

PackageWhat it contains
github.com/surrealdb/surrealdb.go/v2/pkg/connectionThe 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, .../httpThe WebSocket and HTTP connections, for a custom connection.
github.com/surrealdb/surrealdb.go/v2/pkg/constantsSentinel errors, such as ErrSessionClosed.
github.com/surrealdb/surrealdb.go/v2/contrib/surrealqlThe query builder.
github.com/surrealdb/surrealdb.go/v2/contrib/rewsA reconnecting WebSocket connection with its own retry strategies.
github.com/surrealdb/surrealdb.go/v2/memoryThe Agent Memory client.

The packages under contrib/ are outside the backward compatibility guarantee of the SDK. Their API can change in a minor release.

  • Go 1.24 or later

  • SurrealDB 3.3.0 or later, before 5.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).

Was this page helpful?