# surrealdb-python

Instructions for the official SurrealDB Python SDK, connecting over WebSocket or running embedded in memory or from a file.

Skill by SurrealDB. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add surrealdb/agent-skills --skill surrealdb-python
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add surrealdb/agent-skills --skill surrealdb-python -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 368. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/surrealdb/agent-skills/surrealdb-python)

## Source

[Open the source](https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealdb-python). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: surrealdb-python
description: "Using SurrealDB with the Python SDK, covering both client/server mode (WebSocket) and embedded mode (in-memory or file-based). Use when connecting to SurrealDB from Python, using the surrealdb Python package, running SurrealDB embedded without a server, or performing CRUD operations from Python code. Triggers: surrealdb Python, Surreal(), AsyncSurreal(), Python SDK, embedded SurrealDB, mem://, file://."
metadata:
  author: surrealdb
  version: "0.1.0"
---

# SurrealDB Python SDK

## Running SurrealDB (Server Mode)

Persist data with RocksDB:

```bash
surreal start -u root -p root rocksdb:database
```

In-memory:

```bash
surreal start -u root -p root
```

## Client/Server Mode

Connect via WebSocket using the `Surreal` context manager:

```python
from surrealdb import Surreal

with Surreal("ws://localhost:8000/rpc") as db:
    db.signin({"username": "root", "password": "root"})
    db.use("namespace_test", "database_test")

    db.create(
        "person",
        {
            "user": "me",
            "password": "safe",
            "marketing": True,
            "tags": ["python", "documentation"],
        },
    )

    print(db.select("person"))

    print(db.update("person", {
        "user": "you",
        "password": "very_safe",
        "marketing": False,
        "tags": ["Awesome"],
    }))

    print(db.delete("person"))

    db.query("""
    insert into person {
        user: 'me',
        password: 'very_safe',
        tags: ['python', 'documentation']
    };
    """)

    print(db.query("select * from person"))

    print(db.query("""
    update person content {
        user: 'you',
        password: 'more_safe',
        tags: ['awesome']
    };
    """))

    print(db.query("delete person"))
```

## Embedded Mode

Run SurrealDB directly inside your Python process — no server required.

- **In-memory**: `Surreal("mem://")` / `AsyncSurreal("mem://")`
- **File-based persistence**: `Surreal(f"file://{db_path}")` / `AsyncSurreal(f"file://{db_path}")`

See [references/embedded.md](references/embedded.md) for a complete async
example with file-based persistence.
````

- Previous: [inngest-agent-evals](https://syn4pse.dev/terminal/inngest-agent-evals.md)
- Next: [surrealql-performance](https://syn4pse.dev/terminal/surrealql-performance.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
