surreal-orm-lite 0.4.0__tar.gz → 0.6.0__tar.gz

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.6.0}/CHANGELOG.md

@@ -5,6 +5,89 @@ 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
+
+- **Q Objects**: Django-style composable query expressions for complex filters
+  - `Q(field=value)` for basic conditions
+  - `Q(...) | Q(...)` for OR queries
+  - `Q(...) & Q(...)` for AND queries
+  - `~Q(...)` for NOT queries
+  - Nested combinations: `Q(age__gte=18) & (Q(role="admin") | Q(role="mod"))`
+
+- **Parameterized Filters**: All filter values now use parameterized variables (`$_fN`) instead of string interpolation, preventing SQL injection
+
+- **New Lookup Operators**:
+  - `not_in` - NOT IN operator
+  - `not_contains` - CONTAINSNOT operator
+  - `containsall` - CONTAINSALL operator
+  - `containsany` - CONTAINSANY operator
+
+- **`-field` Ordering Shorthand**: Prefix field with `-` for descending order
+  - `order_by("-created_at")` instead of `order_by("created_at", OrderBy.DESC)`
+  - Multi-field ordering: `order_by("-age", "name")`
+
+- **Bulk Operations**:
+  - `bulk_create(models)` - Create multiple records via SDK's `insert()`
+  - `bulk_update(**kwargs)` - Update all matching records with parameterized SET clause
+  - `bulk_delete()` - Delete all matching records, returns count
+
+- New `Q` class exported from `surreal_orm_lite`
+- New test file `tests/test_v050.py` for all v0.5.0 features
+
+### Changed
+
+- `_compile_query()`, `_compile_aggregation_query()`, `_compile_group_by_query()` now return `tuple[str, dict]` with parameterized variables
+- `_execute_query()` now accepts optional `variables` parameter
+- `filter()` now accepts `*args: Q` positional arguments alongside keyword filters
+- `order_by()` now accepts multiple fields with `-field` prefix support
+- `_build_where()` replaces `_build_where_clauses()` and returns parameterized WHERE clause
+- Shared `parse_lookup()` and `build_filter_condition()` functions moved to `utils.py`
+- Fixed `isnull` lookup: now correctly generates `IS NULL`/`IS NOT NULL`
+
 ## [0.4.0] - 2026-02-07
 
 ### Added

{surreal_orm_lite-0.4.0 → surreal_orm_lite-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-orm-lite
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -31,7 +31,7 @@ License: # MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: async,database,orm,pydantic,surrealdb
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: Pydantic :: 2
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -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
@@ -154,9 +156,9 @@ users = await User.objects().filter(
     name__startswith="A"
 ).exec()
 
-# Ordering
+# Ordering (with -field shorthand for DESC)
 users = await User.objects().order_by("name").exec()
-users = await User.objects().order_by("age", OrderBy.DESC).exec()
+users = await User.objects().order_by("-age", "name").exec()
 
 # Pagination
 users = await User.objects().limit(10).offset(20).exec()
@@ -181,30 +183,110 @@ results = await User.objects().query(
 
 ## Features
 
-| Feature               | Status |
-| --------------------- | ------ |
-| Async/await support   | ✅     |
-| Pydantic validation   | ✅     |
-| CRUD operations       | ✅     |
-| QuerySet with filters | ✅     |
-| Django-style lookups  | ✅     |
-| Custom primary keys   | ✅     |
-| HTTP connections      | ✅     |
-| WebSocket connections | ✅     |
-| Aggregations          | ✅     |
-| GROUP BY              | ✅     |
-| Model Signals         | ✅     |
+| Feature                | Status |
+| ---------------------- | ------ |
+| Async/await support    | ✅     |
+| Pydantic validation    | ✅     |
+| CRUD operations        | ✅     |
+| QuerySet with filters  | ✅     |
+| Django-style lookups   | ✅     |
+| Custom primary keys    | ✅     |
+| HTTP connections       | ✅     |
+| WebSocket connections  | ✅     |
+| Aggregations           | ✅     |
+| GROUP BY               | ✅     |
+| Model Signals          | ✅     |
+| Raw SurrealQL queries  | ✅     |
+| Q Objects (OR/AND/NOT) | ✅     |
+| Parameterized filters  | ✅     |
+| Bulk operations        | ✅     |
+| `-field` ordering      | ✅     |
+| Relations & Graph      | ✅     |
+| FETCH clause           | ✅     |
 
 ### Supported Filter Lookups
 
 - `exact` (default)
 - `gt`, `gte`, `lt`, `lte`
-- `in`
-- `contains`, `icontains`
-- `startswith`, `istartswith`
-- `endswith`, `iendswith`
+- `in`, `not_in`
+- `contains`, `not_contains`
+- `containsall`, `containsany`
+- `startswith`, `endswith`
+- `like`, `ilike`
+- `match`, `regex`
+- `isnull`
+
+### 5. Q Objects (Complex Queries)
+
+```python
+from surreal_orm_lite import Q
+
+# OR queries
+users = await User.objects().filter(Q(name="Alice") | Q(name="Bob")).exec()
+
+# NOT queries
+active = await User.objects().filter(~Q(status="banned")).exec()
+
+# Complex combinations
+results = await User.objects().filter(
+    Q(age__gte=18) & (Q(role="admin") | Q(role="mod"))
+).exec()
+
+# Mix Q objects with keyword filters
+results = await User.objects().filter(
+    Q(role="admin") | Q(role="mod"),
+    age__gte=25
+).exec()
+```
+
+### 6. Bulk Operations
+
+```python
+# Bulk create
+users = [User(name="Alice", age=30), User(name="Bob", age=25)]
+created = await User.objects().bulk_create(users)
+
+# Bulk update (returns count of updated records)
+count = await User.objects().filter(status="pending").bulk_update(status="active")
+
+# Bulk delete (returns count of deleted records)
+count = await User.objects().filter(status="inactive").bulk_delete()
+```
+
+### 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)
 
-### 5. Aggregations
+# 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
@@ -230,7 +312,7 @@ results = await User.raw_query(
 )
 ```
 
-### 6. Model Signals
+### 10. Model Signals
 
 ```python
 from surreal_orm_lite import pre_save, post_save, pre_delete, post_delete
@@ -250,17 +332,17 @@ async def on_user_deleting(sender, instance, **kwargs):
 
 **Available signals:**
 
-| Signal          | When                        | Extra kwargs     |
-| --------------- | --------------------------- | ---------------- |
-| `pre_save`      | Before `save()`             |                  |
-| `post_save`     | After `save()`              | `created`        |
-| `pre_update`    | Before `update()`/`merge()` | `update_fields`  |
-| `post_update`   | After `update()`/`merge()`  | `update_fields`  |
-| `pre_delete`    | Before `delete()`           |                  |
-| `post_delete`   | After `delete()`            |                  |
-| `around_save`   | Wraps `save()`              |                  |
-| `around_update` | Wraps `update()`/`merge()`  | `update_fields`  |
-| `around_delete` | Wraps `delete()`            |                  |
+| Signal          | When                        | Extra kwargs    |
+| --------------- | --------------------------- | --------------- |
+| `pre_save`      | Before `save()`             |                 |
+| `post_save`     | After `save()`              | `created`       |
+| `pre_update`    | Before `update()`/`merge()` | `update_fields` |
+| `post_update`   | After `update()`/`merge()`  | `update_fields` |
+| `pre_delete`    | Before `delete()`           |                 |
+| `post_delete`   | After `delete()`            |                 |
+| `around_save`   | Wraps `save()`              |                 |
+| `around_update` | Wraps `update()`/`merge()`  | `update_fields` |
+| `around_delete` | Wraps `delete()`            |                 |
 
 **Around signals** use async generators to wrap operations:
 
@@ -305,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   |
 
 ---
 
@@ -326,16 +410,62 @@ Contributions are welcome! Please:
 
 ---
 
-## Advanced Features?
+## Roadmap
 
-This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. Due to current SDK limitations, some advanced features cannot be implemented here.
+| Version | Theme                         | Status      |
+| ------- | ----------------------------- | ----------- |
+| v0.2.x  | Core ORM (CRUD, QuerySet)     | ✅ Released |
+| 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             | ✅ Released |
+| v0.7.0  | Transactions ORM              | 📋 Planned  |
+| v0.8.0  | SurrealFunc & Computed Fields | 📋 Planned  |
+| v0.9.0  | Field Aliases & DX            | 📋 Planned  |
+| v1.0.0  | Production Ready              | 📋 Planned  |
 
-For a feature-rich ORM with relations, transactions, and more, see:
+See [docs/ROADMAP.md](docs/ROADMAP.md) for full details.
 
-- **GitHub**: [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
-- **PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
+---
 
-When the official SDK supports additional features, they will be incorporated into this lite version.
+## SurrealDB-ORM-lite vs SurrealDB-ORM
+
+This project prioritizes **stability and compatibility** with the official SurrealDB Python SDK. The full [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) uses a custom SDK for advanced features.
+
+| Feature                   | ORM-lite (official SDK) | ORM (custom SDK) |
+| ------------------------- | ----------------------- | ---------------- |
+| CRUD & QuerySet           | ✅                      | ✅               |
+| Aggregations & GROUP BY   | ✅                      | ✅               |
+| Model Signals             | ✅                      | ✅               |
+| Bulk Operations           | ✅                      | ✅               |
+| Q Objects (OR/AND/NOT)    | ✅                      | ✅               |
+| Parameterized Filters     | ✅                      | ✅               |
+| Relations & Graph         | ✅                      | ✅               |
+| FETCH clause              | ✅                      | ✅               |
+| Transactions (tx=)        | v0.7.0                  | ✅               |
+| SurrealFunc & Computed    | v0.8.0                  | ✅               |
+| Field Aliases             | v0.9.0                  | ✅               |
+| Retry, Logging, Metrics   | v0.10.0                 | ✅               |
+| Live Models / CDC         | ❌                      | ✅               |
+| Vector / Full-Text Search | ❌                      | ✅               |
+| Hybrid Search (RRF)       | ❌                      | ✅               |
+| Migrations & CLI          | ❌                      | ✅               |
+| JWT Authentication        | ❌                      | ✅               |
+| Schema Introspection      | ❌                      | ✅               |
+| Connection Pool           | ❌                      | ✅               |
+| CBOR Protocol             | ❌                      | ✅               |
+| Subqueries & Query Cache  | ❌                      | ✅               |
+| Geospatial Fields         | ❌                      | ✅               |
+| DEFINE EVENT              | ❌                      | ✅               |
+| Test Fixtures & Factories | ❌                      | ✅               |
+| Atomic Array Operations   | ❌                      | ✅               |
+
+**Choose ORM-lite** if you want the official SDK, minimal dependencies, and core ORM features.
+
+**Choose ORM** if you need live queries, migrations, authentication, vector search, or advanced features.
+
+- **SurrealDB-ORM GitHub**: [github.com/EulogySnowfall/SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/)
+- **SurrealDB-ORM PyPI**: [surrealdb-orm](https://pypi.org/project/surrealdb-orm/)
 
 ---
 
@@ -356,3 +486,4 @@ GitHub: [@EulogySnowfall](https://github.com/EulogySnowfall)
 
 - [SurrealDB](https://surrealdb.com/) - The database
 - [surrealdb.py](https://github.com/surrealdb/surrealdb.py) - Official Python SDK
+- [SurrealDB-ORM](https://github.com/EulogySnowfall/SurrealDB-ORM/) - Full-featured ORM with custom SDK