Session

The Session struct represents an additional SurrealDB session on a WebSocket connection. Each session has its own authentication state, namespace and database selection, and connection variables. Sessions require SurrealDB v3+ and a WebSocket connection.

Session satisfies the sendable constraint, so all generic functions like Query, Select, Create, etc. accept *Session directly.

Source: session.go

Creating a Session

db.Attach()

Creates a new session on the WebSocket connection. The session starts unauthenticated and without a selected namespace or database.

session, err := db.Attach(ctx)

Returns: (*Session, error)

Returns ErrSessionsNotSupported if the connection is not WebSocket.

Examples

session, err := db.Attach(ctx)
if err != nil {
    log.Fatal(err)
}
defer session.Detach(ctx)

session.SignIn(ctx, surrealdb.Auth{Username: "root", Password: "root"})
session.Use(ctx, "my_ns", "my_db")

results, err := surrealdb.Query[[]Person](ctx, session, "SELECT * FROM persons", nil)

Properties

.ID()

Returns the session's UUID.

id := session.ID()

Returns: *models.UUID

Methods

.Detach()

Removes the session from the server. After calling .Detach(), the session cannot be used.

err := session.Detach(ctx)

Returns: error

Returns ErrSessionClosed if the session has already been detached.

.Begin()

Starts a new interactive transaction within this session.

tx, err := session.Begin(ctx)

Returns: (*Transaction, error) — see Transaction

Returns ErrSessionClosed if the session has been detached.

.SignIn()

Signs in an existing user within this session.

token, err := session.SignIn(ctx, authData)

Returns: (string, error)

.SignInWithRefresh()

Signs in with refresh token support within this session. SurrealDB v3+ only.

tokens, err := session.SignInWithRefresh(ctx, authData)

Returns: (*Tokens, error)

.SignUp()

Signs up a new record user within this session.

token, err := session.SignUp(ctx, authData)

Returns: (string, error)

.SignUpWithRefresh()

Signs up with refresh token support within this session. SurrealDB v3+ only.

tokens, err := session.SignUpWithRefresh(ctx, authData)

Returns: (*Tokens, error)

.Authenticate()

Authenticates this session with a JWT token.

err := session.Authenticate(ctx, token)

Returns: error

.Invalidate()

Invalidates the current authentication for this session.

err := session.Invalidate(ctx)

Returns: error

.Use()

Selects the namespace and database for this session.

err := session.Use(ctx, ns, database)

Returns: error

.Let()

Defines a variable scoped to this session.

err := session.Let(ctx, key, val)

Returns: error

.Unset()

Removes a variable from this session.

err := session.Unset(ctx, key)

Returns: error

.Info()

Returns the record of the currently authenticated user in this session.

info, err := session.Info(ctx)

Returns: (map[string]any, error)

.Version()

Returns the SurrealDB version information.

ver, err := session.Version(ctx)

Returns: (*VersionData, error)

.LiveNotifications()

Returns the notification channel for a live query.

ch, err := session.LiveNotifications(liveQueryID)

Returns: (chan connection.Notification, error)

.CloseLiveNotifications()

Closes the notification channel for a live query.

err := session.CloseLiveNotifications(liveQueryID)

Returns: error

See Also

• DB for the main client reference

• Transaction for session-scoped transactions

• Multiple sessions for session usage patterns

• Errors for ErrSessionClosed and ErrSessionsNotSupported