Multiple sessions

The Python SDK supports creating multiple isolated sessions within a single WebSocket connection. Each session maintains its own namespace, database, and authentication state, allowing you to perform independent operations without opening additional connections.

This page covers how to create sessions, isolate their scope, authenticate independently, and close them when no longer needed.

API references

Creating a session

Call .new_session() on an existing connection to create a new session. The async variant returns an AsyncSurrealSession and the sync variant returns a BlockingSurrealSession. Each session operates independently from the parent connection and other sessions.

from surrealdb import Surreal

with Surreal("ws://localhost:8000") as db:
    db.use("surrealdb", "docs")
    db.signin({"username": "root", "password": "secret"})

    session = db.new_session()

A new session starts with the parent connection's identity, but nothing else from it. If the connection holds a token, .new_session() authenticates the session with that token, so the session begins as the same user. As the connection's namespace and database are not carried over, .use() can be called on the session, as the examples below do. The exception is a token whose own claims name a namespace and database, since those travel with the identity rather than with the connection.

Isolating namespace and database

Each session can target a different namespace and database by calling .use(). Changes to one session's scope do not affect the parent connection or any other session.

session_a = db.new_session()
session_a.use("surrealdb", "docs")

session_b = db.new_session()
session_b.use("surrealdb", "staging")

docs_users = session_a.select("users")
staging_users = session_b.select("users")

In the example above, session_a reads from the docs database while session_b reads from staging, both over the same underlying WebSocket connection.

Independent authentication

Each session can authenticate as a different user. This is useful when you need to perform operations on behalf of multiple users without managing separate connections.

Signing in on a session replaces the identity it started with, so a session only acts as the connection's user until you sign it in as someone else.

session_admin = db.new_session()
session_admin.use("surrealdb", "docs")
session_admin.signin({"username": "root", "password": "secret"})

session_user = db.new_session()
session_user.use("surrealdb", "docs")
session_user.signin({
    "namespace": "surrealdb",
    "database": "docs",
    "access": "account",
    "variables": {
        "email": "info@surrealdb.com",
        "password": "123456",
    },
})

all_records = session_admin.select("users")

own_record = session_user.info()

In the example above, session_admin has root-level access while session_user is authenticated as a record user. Each session's permissions are enforced independently.

Closing a session

When a session is no longer needed, call .close_session() to detach it from the connection and release its resources. The parent connection and other sessions remain active.

session.close_session()

Closing the parent connection automatically closes all sessions associated with it.

Learn more

• •

  SurrealSession API reference for session method signatures

• •

  Transactions for transaction support within sessions

• •

  Authentication for signing in within sessions

• •

  Connecting to SurrealDB for WebSocket connection setup