surrealdb
Advanced tools
The official SurrealDB SDK for Python.
This project uses uv for dependency management and hatch as the build tool.
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
This project follows library best practices for dependency management:
>= instead of exact pins for maximum compatibilityInstall dependencies:
# Install main dependencies
uv sync
# Install with dev dependencies (linting, type checking, testing)
uv sync --group dev
Run development tools:
# Run linting
uv run ruff check src/
# Run formatting
uv run ruff format src/
# Run type checking
uv run mypy --explicit-package-bases src/
# Run tests (with coverage)
uv run scripts/run_tests.sh
# Or directly:
uv run pytest --cov=src/surrealdb --cov-report=term-missing --cov-report=html
Build the project:
uv build
We use a multi-tier testing strategy to ensure compatibility across SurrealDB versions:
# Test with default version (latest stable)
docker-compose up -d
uv run scripts/run_tests.sh
# Test against specific version
./scripts/test-versions.sh v2.1.8
# Test against different v2.x versions
SURREALDB_VERSION=v2.0.5 uv run scripts/run_tests.sh
SURREALDB_VERSION=v2.3.6 uv run scripts/run_tests.sh
Tests are designed to be version-agnostic across all supported SurrealDB v2.x versions:
View the SDK documentation here.
# Using pip
pip install surrealdb
# Using uv
uv add surrealdb
In this short guide, you will learn how to install, import, and initialize the SDK, as well as perform the basic data manipulation queries.
This guide uses the Surreal class, but this example would also work with AsyncSurreal class, with the addition of await in front of the class methods.
pip install surrealdb
# Import the Surreal class
from surrealdb import Surreal
# Using a context manger to automatically connect and disconnect
with Surreal("ws://localhost:8000/rpc") as db:
db.signin({"username": 'root', "password": 'root'})
db.use("namepace_test", "database_test")
# Create a record in the person table
db.create(
"person",
{
"user": "me",
"password": "safe",
"marketing": True,
"tags": ["python", "documentation"],
},
)
# Read all the records in the table
print(db.select("person"))
# Update all records in the table
print(db.update("person", {
"user":"you",
"password":"very_safe",
"marketing": False,
"tags": ["Awesome"]
}))
# Delete all records in the table
print(db.delete("person"))
# You can also use the query method
# doing all of the above and more in SurrealQl
# In SurrealQL you can do a direct insert
# and the table will be created if it doesn't exist
# Create
db.query("""
insert into person {
user: 'me',
password: 'very_safe',
tags: ['python', 'documentation']
};
""")
# Read
print(db.query("select * from person"))
# Update
print(db.query("""
update person content {
user: 'you',
password: 'more_safe',
tags: ['awesome']
};
"""))
# Delete
print(db.query("delete person"))
SurrealDB can also run embedded directly within your Python application natively. This provides a fully-featured database without needing a separate server process.
The embedded database is included when you install surrealdb:
pip install surrealdb
For source builds, you'll need Rust toolchain and maturin:
uv run maturin develop --release
Perfect for embedded applications, development, testing, caching, or temporary data.
import asyncio
from surrealdb import AsyncSurreal
async def main():
# Create an in-memory database (can use "mem://" or "memory")
async with AsyncSurreal("memory") as db:
await db.use("test", "test")
await db.signin({"username": "root", "password": "root"})
# Use like any other SurrealDB connection
person = await db.create("person", {
"name": "John Doe",
"age": 30
})
print(person)
people = await db.select("person")
print(people)
asyncio.run(main())
For persistent local storage:
import asyncio
from surrealdb import AsyncSurreal
async def main():
# Create a file-based database (can use "file://" or "surrealkv://")
async with AsyncSurreal("file://mydb") as db:
await db.use("test", "test")
await db.signin({"username": "root", "password": "root"})
# Data persists across connections
await db.create("company", {
"name": "Acme Corp",
"employees": 100
})
companies = await db.select("company")
print(companies)
asyncio.run(main())
The embedded database also supports the blocking API:
from surrealdb import Surreal
# In-memory (can use "mem://" or "memory")
with Surreal("memory") as db:
db.use("test", "test")
db.signin({"username": "root", "password": "root"})
person = db.create("person", {"name": "Jane"})
print(person)
# File-based
with Surreal("file://mydb") as db:
db.use("test", "test")
db.signin({"username": "root", "password": "root"})
company = db.create("company", {"name": "TechStart"})
print(company)
Use Embedded (memory, mem://, file://, or surrealkv://) when:
Use Remote (ws:// or http://) when:
For more examples, see the examples/embedded/ directory.
Now that you have learned the basics of the SurrealDB SDK for Python, you can learn more about the SDK and its methods in the methods section and data types section.
Contributions to this library are welcome! If you encounter issues, have feature requests, or want to make improvements, feel free to open issues or submit pull requests.
If you want to contribute to the Github repo please read the general contributing guidelines on concepts such as how to create a pull requests here.
To contribute, it's a good idea to get the repo up and running first. We can do this by running the tests. If the tests pass, your PYTHONPATH works and the client is making successful calls to the database. To do this we must run the database with the following command:
# if the docker-compose binary is installed
docker-compose up -d
# if you are running docker compose directly through docker
docker compose up -d
Now that the database is running, we can enter a terminal session with all the requirements installed and PYTHONPATH configured with the command below:
bash scripts/term.sh
You will now be running an interactive terminal through a python virtual environment with all the dependencies installed. We can now run the tests with the following command:
pytest --cov=src/surrealdb --cov-report=term-missing --cov-report=html
The number of tests might increase but at the time of writing this you should get a printout like the one below:
================================ test session starts ================================
platform ...
collected 227 items
....................................................................................
... (test output)
---------- coverage: platform ... -----------
Name Stmts Miss Cover Missing
---------------------------------------------------------
src/surrealdb/....
...
============================= 227 passed in 6.31s ================================
Finally, we clean up the database with the command below:
# if the docker-compose binary is installed
docker-compose down
# if you are running docker compose directly through docker
docker compose down
To exit the terminal session merely execute the following command:
exit
And there we have it, our tests are passing.
Test against different SurrealDB versions using environment variables:
# Test with latest v2.x (default: v2.3.6)
uv run scripts/run_tests.sh
# Test with specific v2.x version
SURREALDB_VERSION=v2.1.8 docker-compose up -d surrealdb
uv run scripts/run_tests.sh
# Use different profiles for testing specific v2.x versions
docker-compose --profile v2-0 up -d # v2.0.5 on port 8020
docker-compose --profile v2-1 up -d # v2.1.8 on port 8021
docker-compose --profile v2-2 up -d # v2.2.6 on port 8022
docker-compose --profile v2-3 up -d # v2.3.6 on port 8023
Use the test script for systematic testing:
# Test latest version with all tests
./scripts/test-versions.sh
# Test specific version
./scripts/test-versions.sh v2.1.8
# Test specific test directory
./scripts/test-versions.sh v2.3.6 tests/unit_tests/data_types
The CI automatically tests against multiple versions:
# Build the image
docker build -t surrealdb-python:latest .
# Run with uv
docker run -it surrealdb-python:latest uv run python -c "import surrealdb; print('Ready!')"
# Run tests in container
docker run -it surrealdb-python:latest uv run python -m unittest discover -s tests
# Start latest SurrealDB for development
docker-compose up -d
# Start specific version for testing
SURREALDB_VERSION=v2.1.8 docker-compose up -d
# View logs
docker-compose logs -f surrealdb
The official SurrealDB Python SDK.
Note: This SDK works seamlessly with SurrealDB versions v2.0.0 to v2.3.6, ensuring compatibility with the latest features. The embedded database functionality is included in pre-built wheels on PyPI.
Install the SDK:
# Using pip
pip install surrealdb
# Using uv
uv add surrealdb
Start SurrealDB (using Docker):
docker run --rm -p 8000:8000 surrealdb/surrealdb:v2.3.6 start --allow-all
Connect and query:
from surrealdb import Surreal
async def main():
async with Surreal("ws://localhost:8000/rpc") as db:
await db.signin({"user": "root", "pass": "root"})
await db.use("test", "test")
# Create
person = await db.create("person", {"name": "John", "age": 30})
print(person)
# Query
people = await db.select("person")
print(people)
import asyncio
asyncio.run(main())
This project uses uv for fast dependency management and hatch for building.
Install uv (if not already installed):
curl -LsSf https://astral.sh/uv/install.sh | sh
Clone and setup:
git clone https://github.com/surrealdb/surrealdb.py.git
cd surrealdb.py
uv sync --group dev
Activate environment:
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Start SurrealDB v2.3.6
docker compose up -d
# Run tests
export SURREALDB_URL="http://localhost:8000"
uv run python -m unittest discover -s tests
# Test latest v2.x versions
./scripts/test-versions.sh --v2-latest
# Test specific version
./scripts/test-versions.sh v2.1.8
# Test all supported versions
./scripts/test-versions.sh --all
# Development (default - v2.3.6)
docker compose up -d
# Test specific v2.x versions
docker compose --profile v2-0 up -d # v2.0.5 on port 8020
docker compose --profile v2-1 up -d # v2.1.8 on port 8021
docker compose --profile v2-2 up -d # v2.2.6 on port 8022
docker compose --profile v2-3 up -d # v2.3.6 on port 8023
# Format code
uv run ruff format
# Lint code
uv run ruff check
# Type checking
uv run mypy src/
uv run pyright src/
TODO: migrate to basedpyright. Try it with uvx run basedpyright src/
# Build package
uv build
# Publish to PyPI (requires authentication)
uv publish
This Python SDK supports SurrealDB v2.0.0 to v2.3.6. Here's the compatibility matrix:
| Python SDK | SurrealDB Versions | Status |
|---|---|---|
| v1.0.0+ | v2.0.0 - v2.3.6 | ✅ Supported |
| v1.0.0+ | v1.x.x | ❌ Not supported |
The SDK is continuously tested against:
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
To run all tests with coverage reporting:
uv run pytest --cov=src/surrealdb --cov-report=term-missing --cov-report=html
This will:
htmlcov/ directoryTo test a specific file:
uv run pytest tests/unit_tests/connections/test_connection_constructor.py --cov=src/surrealdb
To view the HTML coverage report, open htmlcov/index.html in your browser after running the tests.
FAQs
SurrealDB python client
We found that surrealdb demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub postponed a new billing model for self-hosted Actions after developer pushback, but moved forward with hosted runner price cuts on January 1.
Research
Destructive malware is rising across open source registries, using delays and kill switches to wipe code, break builds, and disrupt CI/CD.
Security News
Socket CTO Ahmad Nassri shares practical AI coding techniques, tools, and team workflows, plus what still feels noisy and why shipping remains human-led.