Sign In

Python SDK Version

API Reference
Core
SurrealSession

AsyncSurrealSession / BlockingSurrealSession

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.

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.

MethodReturnsDescription
.use(namespace, database)NoneSwitch namespace and database for this session.
.query(query, vars)ValueExecute a SurrealQL query.
.signin(vars)TokensSign in within this session.
.signup(vars)TokensSign up within this session.
.authenticate(token)NoneAuthenticate this session with a JWT.
.invalidate()NoneInvalidate this session's authentication.
.let(key, value)NoneDefine a session-scoped variable.
.unset(key)NoneRemove a session-scoped variable.
.select(record)ValueSelect records.
.create(record, data)ValueCreate a record.
.update(record, data)ValueReplace a record.
.merge(record, data)ValueMerge data into a record.
.patch(record, data)ValueApply JSON Patch operations.
.delete(record)ValueDelete records.
.insert(table, data)ValueInsert records.
.insert_relation(table, data)ValueInsert relation records.
.upsert(record, data)ValueUpsert a record.
.live(table, diff)UUIDStart a live query.
.kill(query_uuid)NoneKill 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())

See Also

Edit pageReport an issue

Previous

Surreal

Next

SurrealTransaction