SurrealSession

Isolated session for running queries with independent namespace, database, and authentication state.

A session wraps a WebSocket connection with an isolated session ID. Each session maintains its own namespace, database, variables, and authentication state, independent of other sessions on the same connection.

Sessions are created by calling .new_session() on a WebSocket connection. They are not available on HTTP or embedded connections.

Note

Sessions require a WebSocket connection (ws:// or wss://). Attempting to create a session on an HTTP or embedded connection raises UnsupportedFeatureError.

Source: async_ws.py · blocking_ws.py

Creating a session

Method Syntax

session = db.new_session()

Returns (sync): BlockingSurrealSession Returns (async): AsyncSurrealSession

Examples

Synchronous

from surrealdb import Surreal

db = Surreal("ws://localhost:8000")
db.connect()
db.signin({"username": "root", "password": "root"})

session = db.new_session()
session.use("my_namespace", "my_database")

Asynchronous

from surrealdb import AsyncSurreal

db = AsyncSurreal("ws://localhost:8000")
await db.connect()
await db.signin({"username": "root", "password": "root"})

session = await db.new_session()
await session.use("my_namespace", "my_database")

Inherited methods

A session exposes the same interface as the parent connection. All methods below delegate to the underlying connection, scoped to this session's ID. For full parameter tables and examples, see the Surreal reference.

Method	Returns	Description
`.use(namespace, database)`	`None`	Switch namespace and database for this session.
`.query(query, vars)`	Awaitable / lazy `Value` or `tuple[Value, ...]` builder	Execute one or more SurrealQL statements.
`.signin(vars)`	`Tokens`	Sign in within this session.
`.signup(vars)`	`Tokens`	Sign up within this session.
`.authenticate(token)`	`None`	Authenticate this session with a JWT.
`.invalidate()`	`None`	Invalidate this session's authentication.
`.let(key, value)`	`None`	Define a session-scoped variable.
`.unset(key)`	`None`	Remove a session-scoped variable.
`.select(record)`	`Value`	Select records.
`.create(record, data)`	CRUD builder -> `dict[str, Value]`	Create a record (chain `.content/.replace/.merge/.patch`).
`.update(record, data)`	CRUD builder -> `dict` or `list`	Update records (chain `.content/.replace/.merge/.patch`).
`.upsert(record, data)`	CRUD builder -> `dict` or `list`	Upsert a record (chain `.content/.replace/.merge/.patch`).
`.delete(record)`	CRUD builder -> `dict` or `list`	Delete records.
`.insert(table, data, relation=False)`	Insert builder -> `list[Value]`	Insert records. Pass `relation=True` or chain `.relation()` for `INSERT RELATION`.
`.run(name, args, version)`	`Value`	Call a SurrealDB function.
`.live(table, diff)`	`UUID`	Start a live query.
`.kill(query_uuid)`	`None`	Kill a live query.

Session-specific methods

`.begin_transaction()`

Begins a new transaction scoped to this session. Returns a transaction object that provides query and CRUD methods within the transaction boundary.

Method Syntax

txn = session.begin_transaction()

Returns (sync): BlockingSurrealTransaction Returns (async): AsyncSurrealTransaction

Examples

Synchronous

session = db.new_session()
session.use("my_namespace", "my_database")

txn = session.begin_transaction()
txn.create("users", {"name": "Alice", "email": "alice@example.com"})
txn.create("users", {"name": "Bob", "email": "bob@example.com"})
txn.commit()

Asynchronous

session = await db.new_session()
await session.use("my_namespace", "my_database")

txn = await session.begin_transaction()
await txn.create("users", {"name": "Alice", "email": "alice@example.com"})
await txn.create("users", {"name": "Bob", "email": "bob@example.com"})
await txn.commit()

`.close_session()`

Closes this session on the server, releasing its session ID and any associated state. After calling this method, the session object should not be used.

Method Syntax

session.close_session()

Returns: None

Examples

Synchronous

session = db.new_session()
session.use("my_namespace", "my_database")
result = session.select("users")

session.close_session()

Asynchronous

session = await db.new_session()
await session.use("my_namespace", "my_database")
result = await session.select("users")

await session.close_session()

Complete example

Isolated sessions (sync)

from surrealdb import Surreal, RecordID

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

    # Session A works with the "shop" namespace
    session_a = db.new_session()
    session_a.use("shop", "inventory")
    session_a.create("products", {"name": "Laptop", "price": 999.99})

    # Session B works with a different namespace independently
    session_b = db.new_session()
    session_b.use("analytics", "events")
    session_b.create("page_views", {"page": "/products", "count": 1})

    # Each session has its own authentication state
    session_a.signin({"username": "root", "password": "root"})
    products = session_a.select("products")
    print("Products:", products)

    # Transactions within a session
    txn = session_a.begin_transaction()
    txn.create("products", {"name": "Mouse", "price": 29.99})
    txn.create("products", {"name": "Keyboard", "price": 59.99})
    txn.commit()

    session_a.close_session()
    session_b.close_session()

Isolated sessions (async)

import asyncio
from surrealdb import AsyncSurreal, RecordID

async def main():
    async with AsyncSurreal("ws://localhost:8000") as db:
        await db.use("shop", "inventory")
        await db.signin({"username": "root", "password": "root"})

        session = await db.new_session()
        await session.use("shop", "inventory")
        await session.signin({"username": "root", "password": "root"})

        await session.create("products", {"name": "Laptop", "price": 999.99})

        txn = await session.begin_transaction()
        await txn.create("products", {"name": "Mouse", "price": 29.99})
        await txn.create("products", {"name": "Keyboard", "price": 59.99})
        await txn.commit()

        products = await session.select("products")
        print("Products:", products)

        await session.close_session()

asyncio.run(main())

Note

Creating a session

Examples

Inherited methods

Session-specific methods

.begin_transaction()

Examples

.close_session()

Examples

Complete example

See also

`.begin_transaction()`

`.close_session()`