Connecting to SurrealDB

The Go SDK supports connecting to SurrealDB over WebSocket or HTTP. The FromEndpointURLString factory function inspects the URL scheme and creates the appropriate connection automatically.

This page covers how to create, configure, and manage connections to a SurrealDB instance.

API references

Opening a connection

Use FromEndpointURLString to create a new client and connect to a SurrealDB instance. The function accepts a context.Context for cancellation and a URL string that determines the connection type.

ctx := context.Background()

db, err := surrealdb.FromEndpointURLString(ctx, "ws://localhost:8000")
if err != nil {
	log.Fatal(err)
}
defer db.Close(ctx)

The context controls how long the connection attempt blocks. You can use context.WithTimeout to limit the connection time on unreliable networks:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

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

Connection string protocols

The URL scheme determines the connection type and its capabilities.

WebSocket connections are long-lived and stateful. They support all SDK features including live queries, sessions, and transactions.

HTTP connections are stateless. Each request is independent and requires its own authentication token. Live queries, sessions, and transactions are not available over HTTP.

Using a custom connection

If you need to configure the underlying connection (for example, custom TLS settings or a specific WebSocket implementation), you can create a connection manually and pass it to FromConnection:

import (
	"net/url"

	"github.com/surrealdb/surrealdb.go/pkg/connection"
	"github.com/surrealdb/surrealdb.go/pkg/connection/gorillaws"
)

endpoint, _ := url.Parse("ws://localhost:8000/rpc")
conf := connection.NewConfig(endpoint)
conn := gorillaws.New(conf)

db, err := surrealdb.FromConnection(ctx, conn)

FromConnection calls .Connect(ctx) on the connection for you, so you do not need to call it separately. For auto-reconnecting connections, see Reliable connections.

Selecting a namespace and database

After connecting, use .Use() to select the namespace and database you want to work with. Most operations require a namespace and database to be selected first.

if err := db.Use(ctx, "my_namespace", "my_database"); err != nil {
	log.Fatal(err)
}

You can call .Use() multiple times to switch between namespaces and databases on the same connection.

Effect of connection protocol on token and session duration

WebSocket connections (ws://, wss://) are long-lived and stateful. After authentication, the session persists for the lifetime of the connection. The session duration defaults to NONE, meaning it never expires unless configured otherwise.

HTTP connections (http://, https://) are stateless. Each request requires its own authentication token. The token duration defaults to 1 hour.

The figure below shows which duration ends the session in each case, with the default durations.

You can configure token and session durations using the DURATION clause in DEFINE ACCESS METHOD or DEFINE USER statements.

Closing a connection

Call .Close() to release the underlying connection resources when you are done.

db.Close(ctx)

Use defer db.Close(ctx) immediately after creating the connection to ensure cleanup happens even when errors occur.

Learn more

• •

  DB API reference for complete method signatures and parameters

• •

  Authentication for signing in and managing user sessions

• •

  Error handling for handling connection and authentication errors