---
id: surrealdb
version: "2.0.0"
license: unclear
license_treatment: unclear
maintenance: active
---

# surrealdb — SurrealDB python client

License: unclear · Maintenance: active · Downloads: 151.4K/mo

## 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 above — 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

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

- License: not declared (unclear)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 151.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

surrealdb python client, embedded database python, async database sdk, websocket database connection, multi-model database python, multi-model-database, embedded-database, async-support

[View on SkillFed](https://skillfed.io/packages/surrealdb) · [View on PyPI](https://pypi.org/project/surrealdb/)