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

Official Python client for SurrealDB, supporting both remote (WebSocket/HTTP) and embedded (in-memory or file-based) database connections with synchronous and asynchronous APIs.

Yes, with conditions. The package is actively maintained, supports current Python versions (3.10–3.13), and offers both embedded and remote modes for flexibility. However, verify the license terms before use—the metadata does not specify a license, which is a blocker for some projects. No known security vulnerabilities. Install if you are committed to SurrealDB and need a Python client; avoid if license ambiguity is a dealbreaker.

Install

surrealdb on PyPI

pip install surrealdb

uv add surrealdb

poetry add surrealdb

Installing surrealdb

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.

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"))

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

Verify before relying

• Whether the package's license is compatible with your project's license requirements (license metadata missing).
• Performance characteristics and scalability limits for embedded vs. remote connections under production load.
• Support status and backward compatibility guarantees for the 2.0.0 release.

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

Keywords: SurrealDB, Database

Tags

More Software Development packages