SurrealDB Python Client

2.0.0 verified Fri May 01 auth: no python

Official Python client for SurrealDB, a distributed, multi-model database. Current version 2.0.0, supports Python >=3.10. Active development, releases aligned with SurrealDB server updates.

pip install surrealdb

Common errors

error ModuleNotFoundError: No module named 'surrealdb' ↓

cause Library not installed or installed in wrong environment.

fix

Run 'pip install surrealdb' in the correct Python environment.

error AttributeError: module 'surrealdb' has no attribute 'SurrealDB' ↓

cause Using old import path 'from surrealdb import SurrealDB' with v2.x.

fix

Use 'from surrealdb import Surreal' instead.

error TypeError: object Surreal can't be used in 'await' expression ↓

cause Trying to use sync methods or forgetting 'async' on function definition.

fix

Ensure all Surreal methods are called with 'await' inside an async function.

error ConnectionRefusedError: [Errno 111] Connection refused ↓

cause SurrealDB server not running or wrong URL/port.

fix

Verify server is running and URL is correct (e.g., ws://localhost:8000/rpc).

Warnings

breaking Breaking change in v2.0: The class 'SurrealDB' was renamed to 'Surreal'. Old imports will fail. ↓

fix Use 'from surrealdb import Surreal' instead of 'from surrealdb import SurrealDB'.

breaking Breaking change in v2.0: The client is now fully async. Synchronous methods were removed. ↓

fix Use async/await syntax. Wrap call in asyncio.run().

gotcha Connecting to an HTTPS endpoint requires specifying 'wss://' instead of 'ws://'. Auto-detection is not supported. ↓

fix Use 'wss://host:port/rpc' for secure connections.

Imports

Surreal
wrong
```
from surrealdb import SurrealDB
```
correct
```
from surrealdb import Surreal
```
In v2.x the class is named 'Surreal', not 'SurrealDB' as in older versions.
AsyncSurreal
```
from surrealdb import AsyncSurreal
```
Async client class, available since v2.0.

Quickstart

Connect to SurrealDB, authenticate, use namespace/database, create and select records.

import os
from surrealdb import Surreal

url = os.environ.get('SURREAL_URL', 'ws://localhost:8000/rpc')
nspace = os.environ.get('SURREAL_NS', 'test')
dbname = os.environ.get('SURREAL_DB', 'test')

async def main():
    async with Surreal(url) as db:
        await db.signin({'user': 'root', 'pass': 'root'})
        await db.use(nspace, dbname)
        # Create a record
        created = await db.create('person', {'name': 'John', 'age': 30})
        print(created)
        # Select all records
        records = await db.select('person')
        print(records)

import asyncio
asyncio.run(main())