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.
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
session = db.new_session()Returns (sync): BlockingSurrealSession
Returns (async): AsyncSurrealSession
Examples
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")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.
txn = session.begin_transaction()Returns (sync): BlockingSurrealTransaction
Returns (async): AsyncSurrealTransaction
Examples
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()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.
session.close_session()Returns: None
Examples
session = db.new_session()
session.use("my_namespace", "my_database")
result = session.select("users")
session.close_session()session = await db.new_session()
await session.use("my_namespace", "my_database")
result = await session.select("users")
await session.close_session()Complete example
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()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
Surreal — Connection reference with full method documentation
SurrealTransaction — Transaction reference
Data types — Type aliases and value types
Errors — Error classes reference