surreal-basics

Simple and transparent SurrealDB connection abstraction for Python.

Why surreal-basics?

When working with SurrealDB, you need to manage connections, authentication, and namespaces for each operation. surreal-basics abstracts this complexity, offering:

• Automatic connection: Configure once, use anywhere
• Optimized performance: Persistent (singleton) connections for WebSocket and HTTP
• Smart retry: Automatic handling of transient errors (lock conflicts)
• Consistent API: repo_* functions for async and repo_*_sync for sync

Installation

pip install surreal-basics

Or with uv:

uv add surreal-basics

Compatibility

Built on the official surrealdb 2.x SDK, which supports SurrealDB servers v2.0.0 through v3.x. Requires Python 3.11+.

SurrealDB 3.x note: v3 is stricter than v2 — reading from a table that was never defined (e.g. SELECT * FROM thing before any record exists) raises an error instead of returning an empty list. Define the table or insert a record first. surreal-basics surfaces this difference rather than masking it.

Quick Start

Configuration via environment variables

export SURREAL_HOST=localhost
export SURREAL_PORT=8000
export SURREAL_USER=root
export SURREAL_PASS=root
export SURREAL_NS=test
export SURREAL_DB=test
export SURREAL_MODE=ws  # or "http"

Basic usage

from surreal_basics import repo_query, repo_create, repo_select

# Simple query
results = await repo_query("SELECT * FROM user WHERE active = true")

# Create record
user = await repo_create("user", {"name": "John", "email": "john@test.com"})

# Select by ID
user = await repo_select("user:123")

Synchronous mode

from surreal_basics import repo_query_sync, repo_create_sync

# Same operations, without async/await
results = repo_query_sync("SELECT * FROM user")
user = repo_create_sync("user", {"name": "Mary"})

Programmatic configuration

import surreal_basics

# Configure connection
surreal_basics.init(
    host="localhost",
    port=8000,
    namespace="my_ns",
    database="my_db",
    mode="ws",  # "ws" or "http"
    persistent=True,  # persistent connection (recommended)
)

# Or just change the mode
surreal_basics.mode = "http"

Performance

Benchmarks with 1000 operations each (localhost):

Recommendation: Use WebSocket (mode="ws") for best performance. HTTP is useful for serverless environments or when WebSocket is not available.

API Reference

Async Functions

Sync Functions

All async functions have sync equivalents with _sync suffix:

• repo_query_sync, repo_create_sync, etc.

Configuration

Migrations

surreal-basics includes a built-in migration system for managing SurrealDB schema changes.

Quick start

# Create a migration
sbl-migrate create create_users --dir ./migrations

# Check status
sbl-migrate status --dir ./migrations

# Apply pending migrations
sbl-migrate up --dir ./migrations

# Rollback last migration
sbl-migrate down --dir ./migrations

# Abort if the target isn't the namespace/database you expect
sbl-migrate up --expect-ns acme-prod --expect-db app

Programmatic usage

from surreal_basics.migrate import MigrationRunner, AsyncMigrationRunner

# Sync
runner = MigrationRunner("./migrations")
runner.run_up()

# Async
runner = AsyncMigrationRunner("./migrations")
await runner.run_up()

Migration files use the naming convention NNN_name.surrealql with optional NNN_name_down.surrealql for rollbacks. See docs/migrations.md for full documentation.

Error Handling

from surreal_basics import (
    SurrealDBConnectionError,  # Connection failed
    SurrealDBMigrationError,   # Migration failed
    SurrealDBQueryError,       # Query error (no retry)
    SurrealDBTransientError,   # Transient error (automatic retry)
)

try:
    result = await repo_query("SELECT * FROM user")
except SurrealDBConnectionError as e:
    print(f"Connection failed: {e}")
except SurrealDBQueryError as e:
    print(f"Query error: {e}")

Documentation

See docs/ for complete documentation including:

• Configuration - Environment variables, init() and connection modes
• API Reference - Complete documentation of all functions
• Migrations - Schema migration system

Development

# Clone and install
git clone https://github.com/lfnovo/surreal-basics.git
cd surreal-basics
uv sync

# Run tests
uv run pytest

# Run benchmark
uv run python benchmark_library.py

License

MIT