Multiple sessions

Sessions allow you to create isolated contexts on a single WebSocket connection. Each session has its own authentication state, namespace and database selection, and connection variables. This is useful when a single application needs to serve multiple users or tenants over one connection.

Sessions require a WebSocket connection (ws:// or wss://) and SurrealDB v3 or later.

API References

Creating a session

Call .Attach() on the *DB to create a new session. The session starts unauthenticated and without a selected namespace or database, so you must configure it before making queries.

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

_, err = session.SignIn(ctx, surrealdb.Auth{
	Username: "root",
	Password: "root",
})
if err != nil {
	log.Fatal(err)
}

if err := session.Use(ctx, "my_ns", "my_db"); err != nil {
	log.Fatal(err)
}

Querying with a session

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

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

Each session maintains its own state. Changes to variables, authentication, or namespace on one session do not affect the parent *DB or other sessions.

Session isolation

Sessions are fully isolated from each other and from the parent connection:

• Authentication is independent: signing in on a session does not affect other sessions or the *DB.

• .Use() on a session does not change the namespace/database of other sessions.

• Variables set with .Let() are scoped to the session.

• Live queries started on a session are scoped to that session.

sessionA, _ := db.Attach(ctx)
defer sessionA.Detach(ctx)

sessionB, _ := db.Attach(ctx)
defer sessionB.Detach(ctx)

sessionA.SignIn(ctx, surrealdb.Auth{Username: "admin", Password: "admin"})
sessionA.Use(ctx, "ns_a", "db_a")

sessionB.SignIn(ctx, surrealdb.Auth{Namespace: "ns_b", Database: "db_b", Access: "user_access", Username: "user1", Password: "pass1"})
sessionB.Use(ctx, "ns_b", "db_b")

Starting transactions from a session

Sessions can start their own transactions using .Begin(). The transaction inherits the session's authentication and namespace context.

tx, err := session.Begin(ctx)
if err != nil {
	log.Fatal(err)
}
defer tx.Cancel(ctx)

surrealdb.Create[any](ctx, tx, models.Table("events"), map[string]any{"type": "login"})

if err := tx.Commit(ctx); err != nil {
	log.Fatal(err)
}

See Transactions for more on interactive transactions.

Detaching a session

Call .Detach() to remove the session from the server. After detaching, the session cannot be used and any operations on it return ErrSessionClosed.

if err := session.Detach(ctx); err != nil {
	log.Fatal(err)
}

Use defer session.Detach(ctx) immediately after .Attach() to ensure cleanup.

Learn more

• Session API reference for complete method signatures

• Transactions for interactive transaction support

• Connecting to SurrealDB for WebSocket connection requirements

• Errors reference for session-related error types