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.
Syntax
session, err := db.Attach(ctx)
| Parameter | Type | Description |
|---|
ctx required | context.Context | Context for the operation. |
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.
Syntax
id := session.ID()
Returns: *models.UUID
Methods
.Detach()
Removes the session from the server. After calling .Detach(), the session cannot be used.
Syntax
err := session.Detach(ctx)
Returns: error
Returns ErrSessionClosed if the session has already been detached.
.Begin()
Starts a new interactive transaction within this session.
Syntax
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.
Syntax
token, err := session.SignIn(ctx, authData)
Returns: (string, error)
.SignInWithRefresh()
Signs in with refresh token support within this session. SurrealDB v3+ only.
Syntax
tokens, err := session.SignInWithRefresh(ctx, authData)
Returns: (*Tokens, error)
.SignUp()
Signs up a new record user within this session.
Syntax
token, err := session.SignUp(ctx, authData)
Returns: (string, error)
.SignUpWithRefresh()
Signs up with refresh token support within this session. SurrealDB v3+ only.
Syntax
tokens, err := session.SignUpWithRefresh(ctx, authData)
Returns: (*Tokens, error)
.Authenticate()
Authenticates this session with a JWT token.
Syntax
err := session.Authenticate(ctx, token)
Returns: error
.Invalidate()
Invalidates the current authentication for this session.
Syntax
err := session.Invalidate(ctx)
Returns: error
.Use()
Selects the namespace and database for this session.
Syntax
err := session.Use(ctx, ns, database)
Returns: error
.Let()
Defines a variable scoped to this session.
Syntax
err := session.Let(ctx, key, val)
Returns: error
.Unset()
Removes a variable from this session.
Syntax
err := session.Unset(ctx, key)
Returns: error
.Info()
Returns the record of the currently authenticated user in this session.
Syntax
info, err := session.Info(ctx)
Returns: (map[string]any, error)
.Version()
Returns the SurrealDB version information.
Syntax
ver, err := session.Version(ctx)
Returns: (*VersionData, error)
.LiveNotifications()
Returns the notification channel for a live query.
Syntax
ch, err := session.LiveNotifications(liveQueryID)
Returns: (chan connection.Notification, error)
.CloseLiveNotifications()
Closes the notification channel for a live query.
Syntax
err := session.CloseLiveNotifications(liveQueryID)
Returns: error
See Also
