Reliable connections

Warning

This feature is provided by the contrib/rews package, which is outside of the backward compatibility guarantees of the core SDK. Its API may change without following semantic versioning.

The rews (reliable WebSocket) package wraps a standard WebSocket connection and adds automatic reconnection when the connection is lost. On reconnect, it restores the previous session state including namespace, database, authentication, variables, and live queries.

This is useful for long-running applications that need to survive transient network failures without manual reconnection logic.

API References

Function	Description
`rews.New(newConn, interval, unmarshaler, logger)`	Creates a new auto-reconnecting WebSocket connection
`rews.NewExponentialBackoffRetryer()`	Creates a retryer with exponential backoff and jitter
`rews.NewFixedDelayRetryer(delay, maxRetries)`	Creates a retryer with a fixed delay between attempts

Setting up a reliable connection

Create a rews.Connection by providing a factory function that constructs the underlying WebSocket connection, a check interval for detecting disconnections, a CBOR unmarshaler, and an optional logger.

import (
	"context"
	"net/url"
	"time"

	surrealdb "github.com/surrealdb/surrealdb.go"
	"github.com/surrealdb/surrealdb.go/contrib/rews"
	"github.com/surrealdb/surrealdb.go/pkg/connection"
	"github.com/surrealdb/surrealdb.go/pkg/connection/gorillaws"
	"github.com/surrealdb/surrealdb.go/surrealcbor"
)

endpoint, _ := url.Parse("ws://localhost:8000/rpc")
codec := surrealcbor.New()

conn := rews.New(
	func(ctx context.Context) (*gorillaws.WebSocket, error) {
		conf := connection.NewConfig(endpoint)
		conf.Marshaler = codec
		conf.Unmarshaler = codec
		return gorillaws.New(conf), nil
	},
	5*time.Second,
	codec,
	nil,
)

Then pass the connection to FromConnection to create a *DB:

db, err := surrealdb.FromConnection(ctx, conn)
if err != nil {
	log.Fatal(err)
}
defer db.Close(ctx)

Configuring retry behavior

By default, connection attempts are not retried. Set the Retryer field to enable automatic retries on connection failure.

The ExponentialBackoffRetryer increases the delay between retries exponentially, with optional jitter to avoid thundering herd problems:

retryer := rews.NewExponentialBackoffRetryer()
retryer.MaxRetries = 10
retryer.InitialDelay = 1 * time.Second
retryer.MaxDelay = 30 * time.Second
conn.Retryer = retryer

Field	Default	Description
`InitialDelay`	1s	Delay before the first retry
`MaxDelay`	30s	Maximum delay between retries
`Multiplier`	2.0	Exponential backoff multiplier
`MaxRetries`	0 (infinite)	Maximum retry attempts, 0 for unlimited
`Jitter`	`true`	Add randomness to avoid synchronized retries
`JitterFactor`	0.3	Maximum jitter as a fraction of the delay

For simpler cases, FixedDelayRetryer uses a constant delay:

conn.Retryer = rews.NewFixedDelayRetryer(2*time.Second, 5)

You can also implement the Retryer interface for custom strategies:

type Retryer interface {
	NextDelay(attempt int, lastErr error) (time.Duration, bool)
	Reset()
}

What gets restored on reconnect

When the connection is lost and re-established, rews automatically restores:

Namespace and database -- the last values passed to .Use()
Authentication -- the last token from .SignIn(), .SignUp(), or .Authenticate()
Connection variables -- all variables set with .Let() (and removed with .Unset())
Live queries -- all active live queries are re-subscribed, and notification routing is restored

Note

If the authentication token has expired by the time reconnection occurs, re-authentication will fail. The application is responsible for handling token expiry, for example by using refresh tokens.

Connection states

The rews.Connection tracks its state through a state machine:

State	Description
`Disconnected`	Not connected, initial state
`Connecting`	Connection attempt in progress
`Connected`	Connection established and active
`Closing`	Close requested, shutting down
`Closed`	Fully closed, cannot be reused

Learn more

Connecting to SurrealDB for standard connection setup
Live queries for live query setup that persists across reconnections
DB API reference for FromConnection usage