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.
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) | Value | Execute a SurrealQL query. |
.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) | Value | Create a record. |
.update(record, data) | Value | Replace a record. |
.merge(record, data) | Value | Merge data into a record. |
.patch(record, data) | Value | Apply JSON Patch operations. |
.delete(record) | Value | Delete records. |
.insert(table, data) | Value | Insert records. |
.insert_relation(table, data) | Value | Insert relation records. |
.upsert(record, data) | Value | Upsert a record. |
.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 = db.new_session()
session_a.use("shop", "inventory")
session_a.create("products", {"name": "Laptop", "price": 999.99})
session_b = db.new_session()
session_b.use("analytics", "events")
session_b.create("page_views", {"page": "/products", "count": 1})
session_a.signin({"username": "root", "password": "root"})
products = session_a.select("products")
print("Products:", products)
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
