SurrealDB Python SDK

Running SurrealDB (Server Mode)

Persist data with RocksDB:

surreal start -u root -p root rocksdb:database

In-memory:

surreal start -u root -p root

Client/Server Mode

Connect via WebSocket using the Surreal context manager:

from surrealdb import Surreal

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

    db.create(
        "person",
        {
            "user": "me",
            "password": "safe",
            "marketing": True,
            "tags": ["python", "documentation"],
        },
    )

    print(db.select("person"))

    print(db.update("person", {
        "user": "you",
        "password": "very_safe",
        "marketing": False,
        "tags": ["Awesome"],
    }))

    print(db.delete("person"))

    db.query("""
    insert into person {
        user: 'me',
        password: 'very_safe',
        tags: ['python', 'documentation']
    };
    """)

    print(db.query("select * from person"))

    print(db.query("""
    update person content {
        user: 'you',
        password: 'more_safe',
        tags: ['awesome']
    };
    """))

    print(db.query("delete person"))

Embedded Mode

Run SurrealDB directly inside your Python process — no server required.

• In-memory: Surreal("mem://") / AsyncSurreal("mem://")
• File-based persistence: Surreal(f"file://{dbpath}") / AsyncSurreal(f"file://{dbpath}")

See [references/embedded.md](references/embedded.md) for a complete async example with file-based persistence.