surrealdb

What it is and what it does

surrealdb is the official Python SDK for SurrealDB, a multi-model database that can run as a remote server or embedded directly in your application. It provides both synchronous (Surreal) and asynchronous (AsyncSurreal) APIs for connecting to SurrealDB instances via WebSocket, HTTP, or embedded modes (in-memory or file-based). The package handles authentication, namespace/database selection, and CRUD operations through methods like create(), select(), update(), delete(), and query() for raw SurrealQL.

The SDK depends on aiohttp, requests, websockets, pydantic-core, and typing-extensions to manage network communication and data validation. It supports sessions and transactions on WebSocket connections, and integrates with Pydantic Logfire for observability. Embedded mode is useful for development, testing, and single-application deployments, while remote connections suit multi-application or distributed scenarios.

Use it for

• Build a Python desktop or CLI application with local data storage using embedded in-memory or file-based SurrealDB.
• Develop an async web service that connects to a remote SurrealDB instance via WebSocket for real-time data operations.
• Write integration tests that use in-memory SurrealDB to avoid external dependencies and run tests quickly.
• Implement multi-session transactions on a WebSocket connection for complex, coordinated database operations.
• Add observability to database interactions by instrumenting SurrealDB operations with Pydantic Logfire.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

surrealdb on PyPI

Before you install

Medium install friction due to compiled wheels for multiple platforms (cp39-abi3 across macOS, Linux, Windows). Active maintenance with recent release (113 days old) and ongoing commits. Requires Python 3.10 or later.

Requires a running SurrealDB instance (local or remote) or use embedded mode with "memory" or "file://" URIs. Python 3.10+ required.

License in practice

License status is unclear—no SPDX identifier or raw license text provided in package metadata. Verify the actual license terms before adopting in proprietary or restricted contexts.

Quickstart

pip install surrealdb

from surrealdb import Surreal

with Surreal("ws://localhost:8000/rpc") as db:
    db.signin({"username": "root", "password": "root"})
    db.use("namespace", "database")
    db.create("person", {"name": "Alice"})
    print(db.select("person"))

Package facts

Evidence: surrealdb-2.0.0-cp39-abi3-macosx_10_12_x86_64.whl; surrealdb-2.0.0-cp39-abi3-macosx_11_0_arm64.whl; surrealdb-2.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; surrealdb-2.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; surrealdb-2.0.0-cp39-abi3-musllinux_1_2_aarch64.whl; surrealdb-2.0.0-cp39-abi3-musllinux_1_2_x86_64.whl; surrealdb-2.0.0-cp39-abi3-win_amd64.whl

Tags

More Software Development packages

See also pinotdb · libsql-client · centrifuge-python · databend-driver · opentelemetry-instrumentation-psycopg2 · singlestoredb · ibmcloudant · questdb · logfire · opentelemetry-instrumentation-pymssql