surreal-orm-lite 0.5.0__tar.gz → 0.6.2__tar.gz

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-03-10
+
+### Added
+
+- **Relations & Graph**: Full SurrealDB graph relation support on `BaseSurrealModel`
+  - `relate(edge, target, data=)` — Create graph relations (`RELATE source->edge->target`)
+  - `remove_relation(edge, target)` — Remove a specific relation
+  - `remove_all_relations(edge, direction=)` — Remove all relations of a type (`out`, `in`, `both`)
+  - `get_related(edge, direction=, model_class=)` — Retrieve related records through an edge
+  - `traverse(path)` — Graph traversal via SurrealQL path syntax (e.g. `->follows->User->follows->User`)
+
+- **FETCH Clause**: `QuerySet.fetch(*fields)` resolves record links inline, preventing N+1 queries
+  - `Post.objects().fetch("author", "tags").exec()` generates `SELECT * FROM Post FETCH author, tags;`
+
+- **Validation Utilities**: New security validators in `utils.py`
+  - `validate_edge_name()` — Validates edge/relation table names
+  - `validate_graph_path()` — Validates graph traversal paths (strict arrow-segment structure)
+  - `validate_thing()` — Validates `table:id` record identifiers against injection
+
+- New test file `tests/test_relations.py` with unit + E2E tests
+
+- **CI/CD Workflows**:
+  - `.surrealdb-version` file to pin the tested SurrealDB version (2.6.0)
+  - `surrealdb-security.yml` — Daily SurrealDB 2.X version monitor (test, auto-PR, auto-issue)
+  - `dependabot-automerge.yml` — Auto-merge Dependabot PRs with test validation and version bump
+
+### Changed
+
+- `QuerySet._compile_query()` now appends `FETCH` clause when `fetch()` is used
+- `QuerySet.fetch()` now accumulates fields across chained calls instead of overwriting
+- `QuerySet.variables()` now merges variables across chained calls instead of overwriting
+- Coverage: 92.80%
+
+### Fixed
+
+- **Security**: `_resolve_target_thing()` now validates string targets with `validate_thing()` to prevent SurrealQL injection
+- **Security**: `_get_thing()` now validates the generated `table:id` string to prevent injection via malicious model IDs
+- **Security**: `get_related()` now validates RecordIDs with `validate_thing()` before interpolation
+- **Security**: `$` variable references in filters are now validated against `^\$[a-zA-Z_][a-zA-Z0-9_]*$` pattern
+- **Security**: `validate_graph_path()` regex tightened to require arrow-separated segments (`->` or `<-`) — rejects arbitrary `<>-` combinations
+- Removed misleading case-insensitive lookup aliases (`icontains`, `istartswith`, `iendswith`, `iregex`) that were mapped to case-sensitive SurrealDB operators
+
 ## [0.5.0] - 2026-02-11
 
 ### Added

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.5.0
+Version: 0.6.2
 Summary: Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation.
 Project-URL: Homepage, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
 Project-URL: Documentation, https://github.com/EulogySnowfall/SurrealDB-ORM-lite
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 # Surreal ORM Lite
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
-![SurrealDB](https://img.shields.io/badge/SurrealDB-2.6.0-purple)
+![SurrealDB](https://img.shields.io/badge/SurrealDB-2.6.3-purple)
 ![SDK](https://img.shields.io/badge/SDK-Official%201.0.8-green)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
@@ -74,10 +74,12 @@ This ORM is designed to:
 | Dependency   | Version          |
 | ------------ | ---------------- |
 | Python       | 3.11+            |
-| SurrealDB    | 2.6.0+           |
+| SurrealDB    | >=2.6.x, <3.0    |
 | Official SDK | surrealdb>=1.0.8 |
 | Pydantic     | >=2.12.5         |
 
+> **Note**: The official SurrealDB Python SDK (`surrealdb>=1.0.8`) only supports SurrealDB 2.X. For SurrealDB 3.X support, use the full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) (v0.30.0+).
+
 ---
 
 ## Installation
@@ -199,18 +201,19 @@ results = await User.objects().query(
 | Parameterized filters  | ✅     |
 | Bulk operations        | ✅     |
 | `-field` ordering      | ✅     |
+| Relations & Graph      | ✅     |
+| FETCH clause           | ✅     |
 
 ### Supported Filter Lookups
 
 - `exact` (default)
 - `gt`, `gte`, `lt`, `lte`
 - `in`, `not_in`
-- `contains`, `icontains`, `not_contains`
+- `contains`, `not_contains`
 - `containsall`, `containsany`
-- `startswith`, `istartswith`
-- `endswith`, `iendswith`
+- `startswith`, `endswith`
 - `like`, `ilike`
-- `match`, `regex`, `iregex`
+- `match`, `regex`
 - `isnull`
 
 ### 5. Q Objects (Complex Queries)
@@ -250,7 +253,40 @@ count = await User.objects().filter(status="pending").bulk_update(status="active
 count = await User.objects().filter(status="inactive").bulk_delete()
 ```
 
-### 7. Aggregations
+### 7. Relations & Graph
+
+```python
+# Create a relation
+await user.relate("follows", other_user)
+
+# With data on the edge
+await user.relate("purchased", product, data={"quantity": 2, "price": 29.99})
+
+# Get related records (outgoing)
+following = await user.get_related("follows", direction="out", model_class=User)
+
+# Get related records (incoming)
+followers = await user.get_related("follows", direction="in", model_class=User)
+
+# Remove a specific relation
+await user.remove_relation("follows", other_user)
+
+# Remove all outgoing relations of a type
+await user.remove_all_relations("follows", direction="out")
+
+# Graph traversal
+friends_of_friends = await user.traverse("->follows->User->follows->User")
+```
+
+### 8. FETCH Clause
+
+```python
+# Resolve record links inline (prevents N+1 queries)
+posts = await Post.objects().fetch("author", "tags").exec()
+# Generates: SELECT * FROM Post FETCH author, tags;
+```
+
+### 9. Aggregations
 
 ```python
 from surreal_orm_lite import Count, Sum, Avg, Min, Max
@@ -276,7 +312,7 @@ results = await User.raw_query(
 )
 ```
 
-### 8. Model Signals
+### 10. Model Signals
 
 ```python
 from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
@@ -351,12 +387,14 @@ async with SurrealDBConnectionManager():
 
 ## Compatibility
 
-This ORM is tested and compatible with:
+This ORM is tested and compatible with SurrealDB 2.X only (SDK limitation). For SurrealDB 3.X, use [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) v0.30.0+.
 
-| SurrealDB Version | SDK Version | Status        |
-| ----------------- | ----------- | ------------- |
-| 2.6.0             | 1.0.8       | ✅ Tested     |
-| 2.5.x             | 1.0.8       | ✅ Compatible |
+| SurrealDB Version | SDK Version | Status             |
+| ----------------- | ----------- | ------------------ |
+| 2.6.3             | 1.0.8       | ✅ Tested          |
+| 2.6.x             | 1.0.8       | ✅ Compatible      |
+| 2.5.x             | 1.0.8       | ✅ Compatible      |
+| 3.x               | —           | ❌ Not supported   |
 
 ---
 
@@ -380,7 +418,7 @@ Contributions are welcome! Please:
 | v0.3.0  | Aggregations & Utilities      | ✅ Released |
 | v0.4.0  | Model Signals                 | ✅ Released |
 | v0.5.0  | Bulk Operations & Q Objects   | ✅ Released |
-| v0.6.0  | Relations & Graph             | 📋 Next     |
+| v0.6.0  | Relations & Graph             | ✅ Released |
 | v0.7.0  | Transactions ORM              | 📋 Planned  |
 | v0.8.0  | SurrealFunc & Computed Fields | 📋 Planned  |
 | v0.9.0  | Field Aliases & DX            | 📋 Planned  |
@@ -402,8 +440,8 @@ This project prioritizes **stability and compatibility** with the official Surre
 | Bulk Operations           | ✅                      | ✅               |
 | Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
 | Parameterized Filters     | ✅                      | ✅               |
-| Relations & Graph         | v0.6.0                  | ✅               |
-| FETCH clause              | v0.6.0                  | ✅               |
+| Relations & Graph         | ✅                      | ✅               |
+| FETCH clause              | ✅                      | ✅               |
 | Transactions (tx=)        | v0.7.0                  | ✅               |
 | SurrealFunc & Computed    | v0.8.0                  | ✅               |
 | Field Aliases             | v0.9.0                  | ✅               |

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/README.md

@@ -1,7 +1,7 @@
 # Surreal ORM Lite
 
 ![Python](https://img.shields.io/badge/python-3.11%2B-blue)
-![SurrealDB](https://img.shields.io/badge/SurrealDB-2.6.0-purple)
+![SurrealDB](https://img.shields.io/badge/SurrealDB-2.6.3-purple)
 ![SDK](https://img.shields.io/badge/SDK-Official%201.0.8-green)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 [![codecov](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite/graph/badge.svg)](https://codecov.io/gh/EulogySnowfall/SurrealDB-ORM-lite)
@@ -24,10 +24,12 @@ This ORM is designed to:
 | Dependency   | Version          |
 | ------------ | ---------------- |
 | Python       | 3.11+            |
-| SurrealDB    | 2.6.0+           |
+| SurrealDB    | >=2.6.x, <3.0    |
 | Official SDK | surrealdb>=1.0.8 |
 | Pydantic     | >=2.12.5         |
 
+> **Note**: The official SurrealDB Python SDK (`surrealdb>=1.0.8`) only supports SurrealDB 2.X. For SurrealDB 3.X support, use the full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) (v0.30.0+).
+
 ---
 
 ## Installation
@@ -149,18 +151,19 @@ results = await User.objects().query(
 | Parameterized filters  | ✅     |
 | Bulk operations        | ✅     |
 | `-field` ordering      | ✅     |
+| Relations & Graph      | ✅     |
+| FETCH clause           | ✅     |
 
 ### Supported Filter Lookups
 
 - `exact` (default)
 - `gt`, `gte`, `lt`, `lte`
 - `in`, `not_in`
-- `contains`, `icontains`, `not_contains`
+- `contains`, `not_contains`
 - `containsall`, `containsany`
-- `startswith`, `istartswith`
-- `endswith`, `iendswith`
+- `startswith`, `endswith`
 - `like`, `ilike`
-- `match`, `regex`, `iregex`
+- `match`, `regex`
 - `isnull`
 
 ### 5. Q Objects (Complex Queries)
@@ -200,7 +203,40 @@ count = await User.objects().filter(status="pending").bulk_update(status="active
 count = await User.objects().filter(status="inactive").bulk_delete()
 ```
 
-### 7. Aggregations
+### 7. Relations & Graph
+
+```python
+# Create a relation
+await user.relate("follows", other_user)
+
+# With data on the edge
+await user.relate("purchased", product, data={"quantity": 2, "price": 29.99})
+
+# Get related records (outgoing)
+following = await user.get_related("follows", direction="out", model_class=User)
+
+# Get related records (incoming)
+followers = await user.get_related("follows", direction="in", model_class=User)
+
+# Remove a specific relation
+await user.remove_relation("follows", other_user)
+
+# Remove all outgoing relations of a type
+await user.remove_all_relations("follows", direction="out")
+
+# Graph traversal
+friends_of_friends = await user.traverse("->follows->User->follows->User")
+```
+
+### 8. FETCH Clause
+
+```python
+# Resolve record links inline (prevents N+1 queries)
+posts = await Post.objects().fetch("author", "tags").exec()
+# Generates: SELECT * FROM Post FETCH author, tags;
+```
+
+### 9. Aggregations
 
 ```python
 from surreal_orm_lite import Count, Sum, Avg, Min, Max
@@ -226,7 +262,7 @@ results = await User.raw_query(
 )
 ```
 
-### 8. Model Signals
+### 10. Model Signals
 
 ```python
 from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
@@ -301,12 +337,14 @@ async with SurrealDBConnectionManager():
 
 ## Compatibility
 
-This ORM is tested and compatible with:
+This ORM is tested and compatible with SurrealDB 2.X only (SDK limitation). For SurrealDB 3.X, use [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) v0.30.0+.
 
-| SurrealDB Version | SDK Version | Status        |
-| ----------------- | ----------- | ------------- |
-| 2.6.0             | 1.0.8       | ✅ Tested     |
-| 2.5.x             | 1.0.8       | ✅ Compatible |
+| SurrealDB Version | SDK Version | Status             |
+| ----------------- | ----------- | ------------------ |
+| 2.6.3             | 1.0.8       | ✅ Tested          |
+| 2.6.x             | 1.0.8       | ✅ Compatible      |
+| 2.5.x             | 1.0.8       | ✅ Compatible      |
+| 3.x               | —           | ❌ Not supported   |
 
 ---
 
@@ -330,7 +368,7 @@ Contributions are welcome! Please:
 | v0.3.0  | Aggregations & Utilities      | ✅ Released |
 | v0.4.0  | Model Signals                 | ✅ Released |
 | v0.5.0  | Bulk Operations & Q Objects   | ✅ Released |
-| v0.6.0  | Relations & Graph             | 📋 Next     |
+| v0.6.0  | Relations & Graph             | ✅ Released |
 | v0.7.0  | Transactions ORM              | 📋 Planned  |
 | v0.8.0  | SurrealFunc & Computed Fields | 📋 Planned  |
 | v0.9.0  | Field Aliases & DX            | 📋 Planned  |
@@ -352,8 +390,8 @@ This project prioritizes **stability and compatibility** with the official Surre
 | Bulk Operations           | ✅                      | ✅               |
 | Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
 | Parameterized Filters     | ✅                      | ✅               |
-| Relations & Graph         | v0.6.0                  | ✅               |
-| FETCH clause              | v0.6.0                  | ✅               |
+| Relations & Graph         | ✅                      | ✅               |
+| FETCH clause              | ✅                      | ✅               |
 | Transactions (tx=)        | v0.7.0                  | ✅               |
 | SurrealFunc & Computed    | v0.8.0                  | ✅               |
 | Field Aliases             | v0.9.0                  | ✅               |

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "surreal-orm-lite"
-version = "0.5.0"
+version = "0.6.2"
 description = "Lightweight Django-style ORM for SurrealDB using the official Python SDK. Async support with Pydantic validation."
 readme = "README.md"
 requires-python = ">=3.11"

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/src/surreal_orm_lite/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.0"
+__version__ = "0.6.2"
 
 from .aggregations import Aggregation, Avg, Count, Max, Min, Sum
 from .connection_manager import SurrealDBConnectionManager

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/src/surreal_orm_lite/constants.py

@@ -9,16 +9,12 @@ LOOKUP_OPERATORS = {
     "like": "LIKE",
     "ilike": "ILIKE",
     "contains": "CONTAINS",
-    "icontains": "CONTAINS",
     "not_contains": "CONTAINSNOT",
     "containsall": "CONTAINSALL",
     "containsany": "CONTAINSANY",
     "startswith": "STARTSWITH",
-    "istartswith": "STARTSWITH",
     "endswith": "ENDSWITH",
-    "iendswith": "ENDSWITH",
     "match": "MATCH",
     "regex": "REGEX",
-    "iregex": "REGEX",
     "isnull": "IS",
 }

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/src/surreal_orm_lite/model_base.py

@@ -18,6 +18,7 @@ from .signals import (
     pre_save,
     pre_update,
 )
+from .utils import remove_quotes_for_variables, validate_edge_name, validate_field_name, validate_graph_path, validate_thing
 
 logger = logging.getLogger(__name__)
 
@@ -304,6 +305,224 @@ class BaseSurrealModel(BaseModel):
 
         return self
 
+    # ==================== Relations & Graph ====================
+
+    def _get_thing(self) -> str:
+        """Return ``table:id`` string for this instance."""
+        id_val = self.get_id()
+        if id_val is None:
+            raise SurrealDbError("Cannot use relations on an unsaved model (no id).")
+        thing = f"{self.get_table_name()}:{id_val}"
+        validate_thing(thing)
+        return thing
+
+    @staticmethod
+    def _resolve_target_thing(target: "BaseSurrealModel | str") -> str:
+        """Resolve a target to ``table:id`` string."""
+        if isinstance(target, str):
+            validate_thing(target)
+            return target
+        if isinstance(target, BaseSurrealModel):
+            return target._get_thing()
+        raise TypeError(f"target must be a BaseSurrealModel instance or 'table:id' string, got {type(target).__name__}")
+
+    async def relate(
+        self,
+        edge: str,
+        target: "BaseSurrealModel | str",
+        *,
+        data: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Create a graph relation from this record to the target.
+
+        Args:
+            edge: The relation/edge table name (e.g. ``"follows"``).
+            target: The target model instance or ``"table:id"`` string.
+            data: Optional data to store on the relation edge.
+
+        Returns:
+            The created relation record(s) as returned by the database.
+
+        Example::
+
+            await user.relate("follows", other_user)
+            await user.relate("purchased", product, data={"quantity": 2})
+        """
+        validate_edge_name(edge)
+        source = self._get_thing()
+        target_thing = self._resolve_target_thing(target)
+
+        if data:
+            set_parts: list[str] = []
+            variables: dict[str, Any] = {}
+            for i, (key, value) in enumerate(data.items()):
+                validate_field_name(key, "relation data field")
+                var_name = f"_rd{i}"
+                set_parts.append(f"{key} = ${var_name}")
+                variables[var_name] = value
+            set_clause = " SET " + ", ".join(set_parts)
+            query = f"RELATE {source}->{edge}->{target_thing}{set_clause};"
+        else:
+            variables = {}
+            query = f"RELATE {source}->{edge}->{target_thing};"
+
+        client = await SurrealDBConnectionManager.get_client()
+        result = await client.query(remove_quotes_for_variables(query), variables)
+        return result if isinstance(result, list) else []
+
+    async def remove_relation(
+        self,
+        edge: str,
+        target: "BaseSurrealModel | str",
+    ) -> None:
+        """
+        Remove a specific relation between this record and the target.
+
+        Args:
+            edge: The relation/edge table name.
+            target: The target model instance or ``"table:id"`` string.
+
+        Example::
+
+            await user.remove_relation("follows", other_user)
+            await user.remove_relation("follows", "User:bob")
+        """
+        validate_edge_name(edge)
+        source = self._get_thing()
+        target_thing = self._resolve_target_thing(target)
+
+        query = f"DELETE {edge} WHERE in = {source} AND out = {target_thing};"
+        client = await SurrealDBConnectionManager.get_client()
+        await client.query(query, {})
+
+    async def remove_all_relations(
+        self,
+        edge: str,
+        *,
+        direction: str = "out",
+    ) -> None:
+        """
+        Remove all relations of a given type from or to this record.
+
+        Args:
+            edge: The relation/edge table name.
+            direction: ``"out"`` removes outgoing relations (default),
+                       ``"in"`` removes incoming relations,
+                       ``"both"`` removes all relations involving this record.
+
+        Example::
+
+            await user.remove_all_relations("follows", direction="out")
+            await user.remove_all_relations("follows", direction="both")
+        """
+        validate_edge_name(edge)
+        thing = self._get_thing()
+
+        if direction == "out":
+            query = f"DELETE {edge} WHERE in = {thing};"
+        elif direction == "in":
+            query = f"DELETE {edge} WHERE out = {thing};"
+        elif direction == "both":
+            query = f"DELETE {edge} WHERE in = {thing} OR out = {thing};"
+        else:
+            raise ValueError(f"direction must be 'out', 'in', or 'both', got '{direction}'")
+
+        client = await SurrealDBConnectionManager.get_client()
+        await client.query(query, {})
+
+    async def get_related(
+        self,
+        edge: str,
+        *,
+        direction: str = "out",
+        model_class: type["BaseSurrealModel"] | None = None,
+    ) -> list[Any]:
+        """
+        Get related records through a relation edge.
+
+        Args:
+            edge: The relation/edge table name.
+            direction: ``"out"`` for outgoing relations (default),
+                       ``"in"`` for incoming relations.
+            model_class: Optional model class to deserialize results into.
+
+        Returns:
+            A list of related records (model instances if model_class is provided,
+            otherwise raw dicts/values).
+
+        Example::
+
+            following = await user.get_related("follows", direction="out", model_class=User)
+            followers = await user.get_related("follows", direction="in", model_class=User)
+        """
+        validate_edge_name(edge)
+        thing = self._get_thing()
+
+        if direction == "out":
+            query = f"SELECT VALUE ->{edge}->? FROM ONLY {thing};"
+        elif direction == "in":
+            query = f"SELECT VALUE <-{edge}<-? FROM ONLY {thing};"
+        else:
+            raise ValueError(f"direction must be 'out' or 'in', got '{direction}'")
+
+        client = await SurrealDBConnectionManager.get_client()
+        results = await client.query(query, {})
+
+        if not isinstance(results, list) or len(results) == 0:
+            return []
+
+        # Results from SELECT VALUE ->edge->? are a flat list of record IDs/objects
+        records = results
+
+        if model_class is not None:
+            # If results are RecordIDs, we need to SELECT them
+            if records and isinstance(records[0], RecordID):
+                # RecordIDs come from the database, validate each one before interpolation
+                ids = []
+                for r in records:
+                    rid = str(r)
+                    validate_thing(rid)
+                    ids.append(rid)
+                placeholders = ", ".join(ids)
+                fetch_query = f"SELECT * FROM {placeholders};"
+                records = await client.query(fetch_query, {})
+                if not isinstance(records, list):
+                    return []
+
+            try:
+                return model_class.from_db(records)  # type: ignore
+            except (ValueError, TypeError):
+                return records
+
+        return records
+
+    async def traverse(self, path: str) -> list[Any]:
+        """
+        Execute a graph traversal from this record.
+
+        Args:
+            path: A SurrealQL graph traversal path starting with ``->`` or ``<-``.
+
+        Returns:
+            A list of records found by the traversal.
+
+        Example::
+
+            # Friends of friends
+            fof = await user.traverse("->follows->User->follows->User")
+        """
+        validate_graph_path(path)
+        thing = self._get_thing()
+
+        query = f"SELECT VALUE {path} FROM ONLY {thing};"
+        client = await SurrealDBConnectionManager.get_client()
+        results = await client.query(query, {})
+
+        if isinstance(results, list):
+            return results
+        return []
+
     @classmethod
     def objects(cls) -> Any:
         """

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/src/surreal_orm_lite/query_set.py

@@ -45,6 +45,7 @@ class QuerySet:
         self._order_by: str | None = None
         self._model_table: str = getattr(model, "_table_name", model.__name__)
         self._variables: dict = {}
+        self._fetch_fields: list[str] = []
         self._group_by_fields: list[str] = []
         self._annotations: dict[str, Aggregation] = {}
 
@@ -76,7 +77,7 @@ class QuerySet:
         Returns:
             Self: The current instance for method chaining.
         """
-        self._variables = dict(kwargs.items())
+        self._variables.update(kwargs)
         return self
 
     def filter(self, *args: Q, **kwargs: Any) -> Self:
@@ -185,6 +186,28 @@ class QuerySet:
         self._order_by = ", ".join(order_parts)
         return self
 
+    def fetch(self, *fields: str) -> Self:
+        """
+        Add a FETCH clause to resolve record links inline.
+
+        This prevents N+1 queries by fetching linked records in a single query.
+
+        Args:
+            *fields: Field names to fetch/resolve.
+
+        Returns:
+            Self: The current instance for method chaining.
+
+        Example::
+
+            posts = await Post.objects().fetch("author", "tags").exec()
+            # Generates: SELECT * FROM Post FETCH author, tags;
+        """
+        for field in fields:
+            validate_field_name(field, "FETCH field")
+        self._fetch_fields.extend(fields)
+        return self
+
     # ==================== Internal query building ====================
 
     def _build_where(self) -> tuple[str, dict[str, Any]]:
@@ -243,6 +266,9 @@ class QuerySet:
         if self._offset is not None:
             query += f" START {self._offset}"
 
+        if self._fetch_fields:
+            query += f" FETCH {', '.join(self._fetch_fields)}"
+
         query += ";"
         all_variables = {**self._variables, **where_vars}
         return query, all_variables

{surreal_orm_lite-0.5.0 → surreal_orm_lite-0.6.2}/src/surreal_orm_lite/utils.py

@@ -11,6 +11,17 @@ VALID_FIELD_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9
 # Must start with a letter or underscore (like Python identifiers)
 VALID_ALIAS_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
 
+# Pattern for valid graph traversal paths: arrow-separated segments
+# e.g. ->follows->User, <-follows<-User, ->follows->User->likes->Post
+VALID_GRAPH_PATH_PATTERN = re.compile(r"^(<-|->)[a-zA-Z_][a-zA-Z0-9_]*((<-|->)[a-zA-Z_][a-zA-Z0-9_]*)*$")
+
+# Pattern for valid record thing strings: table:id where both parts are safe
+# ID part allows alphanumeric, underscores, and hyphens
+VALID_THING_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*:[a-zA-Z0-9_`-]+$")
+
+# Pattern for valid SurrealQL variable references: $variable_name
+VALID_VARIABLE_REF_PATTERN = re.compile(r"^\$[a-zA-Z_][a-zA-Z0-9_]*$")
+
 
 def remove_quotes_for_variables(query: str) -> str:
     # Regex to remove single quotes around variables ($)
@@ -56,6 +67,65 @@ def validate_alias_name(alias: str) -> None:
         )
 
 
+def validate_edge_name(edge: str) -> None:
+    """
+    Validate an edge (relation table) name to prevent injection.
+
+    Args:
+        edge: The edge/relation name to validate.
+
+    Raises:
+        ValueError: If the edge name contains invalid characters.
+    """
+    if not edge or not edge.strip():
+        raise ValueError("edge name cannot be empty")
+    if not VALID_ALIAS_PATTERN.match(edge):
+        raise ValueError(
+            f"Invalid edge name '{edge}': must contain only alphanumeric characters "
+            "and underscores, and start with a letter or underscore"
+        )
+
+
+def validate_graph_path(path: str) -> None:
+    """
+    Validate a graph traversal path to prevent injection.
+
+    Accepts paths like ``->follows->User``, ``<-follows<-User``,
+    or mixed ``->follows->User->likes->Post``.
+
+    Args:
+        path: The graph traversal path to validate.
+
+    Raises:
+        ValueError: If the path contains invalid characters or structure.
+    """
+    if not path or not path.strip():
+        raise ValueError("graph path cannot be empty")
+    if not VALID_GRAPH_PATH_PATTERN.match(path):
+        raise ValueError(
+            f"Invalid graph path '{path}': must be arrow-separated segments starting with -> or <- (e.g. '->follows->User')"
+        )
+
+
+def validate_thing(thing: str) -> None:
+    """
+    Validate a ``table:id`` record identifier to prevent injection.
+
+    Args:
+        thing: The record identifier in ``table:id`` format.
+
+    Raises:
+        ValueError: If the thing string is not a valid ``table:id`` format.
+    """
+    if not thing or not thing.strip():
+        raise ValueError("record identifier cannot be empty")
+    if not VALID_THING_PATTERN.match(thing):
+        raise ValueError(
+            f"Invalid record identifier '{thing}': must be in 'table:id' format "
+            "with only alphanumeric characters, underscores, and hyphens"
+        )
+
+
 def parse_lookup(key: str) -> tuple[str, str]:
     """
     Parse a filter key into field name and lookup type.
@@ -109,6 +179,8 @@ def build_filter_condition(field: str, lookup: str, value: Any, counter: int) ->
         return f"{field} {op} ${var_name}", {var_name: list(value)}, counter + 1
     elif isinstance(value, str) and value.startswith("$"):
         # Backward compat: string values starting with $ are variable references
+        if not VALID_VARIABLE_REF_PATTERN.match(value):
+            raise ValueError(f"Invalid variable reference '{value}': must match $variable_name pattern")
         return f"{field} {op} {value}", {}, counter
     else:
         return f"{field} {op} ${var_name}", {var_name: value}, counter + 1