Tapestry

Tapestry is a modern Python ORM for SurrealDB, built on top of Pydantic for robust data validation and type safety.

Tapestry makes it intuitive to work with SurrealDB’s powerful graph database features using familiar Python classes and type hints. Define your schema as Pydantic models, and Tapestry handles the rest - from generating SurrealQL schemas to managing relationships and complex queries.

Key Features

✨ Type Safe: Full type hints and Pydantic validation for better IDE support and fewer runtime errors
🔗 Graph Relationships: First-class support for nodes and edges with intuitive relationship modeling
🚀 Simple & Pythonic: Clean API that feels natural to Python developers
🔍 Query Builder: Expressive query construction with support for graph traversals
📝 Schema Generation: Automatic SurrealQL schema generation from your Python models

Quick Example

from tapestry import Node, Edge
from datetime import date

# Define your models
class Person(Node):
    name: str
    email: str
    date_of_birth: date

class FriendOf(Edge):
    in_: Person
    out_: Person
    since: date

# Use them with SurrealDB
async with db_session as db:
    # Create records
    alice = await Person(
        name="Alice",
        email="alice@example.com",
        date_of_birth=date(1990, 1, 1)
    ).create(db)

    bob = await Person(
        name="Bob",
        email="bob@example.com",
        date_of_birth=date(1992, 5, 15)
    ).create(db)

    # Create relationships
    friendship = await FriendOf(
        in_=alice,
        out_=bob,
        since=date.today()
    ).relate(db)

Installation

Install Tapestry using pip:

pip install tapestry-orm

Or using uv:

uv add tapestry-orm

Requirements

Python 3.12+
SurrealDB 1.0+
Pydantic 2.0+

Why Tapestry?

SurrealDB is a powerful multi-model database that combines SQL, NoSQL, and Graph databases. However, working with it directly requires writing SurrealQL queries as strings, which can be error-prone and lacks the benefits of Python’s type system.

Tapestry bridges this gap by providing:

Type-Safe Schema Definition: Define your database schema using Python classes with full type hints
Automatic Validation: Leverage Pydantic’s validation to catch errors before they reach the database
Intuitive API: Work with database records as Python objects with familiar methods
Graph Operations: Express complex graph traversals using Python operators (>> and <<)
IDE Support: Get autocompletion, type checking, and inline documentation in your IDE

License

Tapestry is open source software, licensed under the MIT License.