sqlobjects 1.10.0__tar.gz → 2.0.1__tar.gz

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 2.0.1 (2026-08-31)
+
+### Fix
+
+- **metadata**: include dialect kwargs in index dedup signature
+
+## 2.0.0 (2026-08-19)
+
+### BREAKING CHANGE
+
+- annotate().group_by().all() with non-primary-key
+grouping and group_by().aggregate() now raise QueryError; both
+previously returned silently wrong results. QuerySet.create() removed
+(never wrote to the database) — use Model.objects.create().
+
+### Feat
+
+- **rules**: stamp installed rule files with the package version
+- **query**: strict GROUP BY semantics, values-mode aggregation, manager-only hints
+- **orm**: support SQLAlchemy expressions as write values
+- **bulk**: make BulkResult a sequence and guarantee insert RETURNING order
+- **session**: add join_ambient option to ctx_session and warn on nested sessions
+- **build**: ship py.typed marker so type checkers see the package as typed
+
 ## 1.10.0 (2026-07-24)
 
 ### Feat

{sqlobjects-1.10.0/sqlobjects.egg-info → sqlobjects-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlobjects
-Version: 1.10.0
+Version: 2.0.1
 Summary: Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/01-database-session-guide.md

@@ -120,14 +120,27 @@ await init_db(
 - **Don't create sessions manually** (use context managers)
 
 ```python
-# Caution: Nested sessions use separate transactions
+# DANGER: Nested ctx_session opens a SECOND physical connection
 async with ctx_session() as session1:
     user = await User.objects.using(session1).create(username="alice")
     async with ctx_session() as session2:
-        # Nesting is safe (Token-based restore), but uses a separate transaction
-        # — session1 won't see session2's uncommitted changes and vice versa
+        # ContextVar restore is safe, but session2 is a separate physical
+        # connection with its own transaction:
+        # - session1 won't see session2's uncommitted changes and vice versa
+        # - if session2 writes a row that session1 holds a lock on, session2
+        #   blocks forever while session1 sits idle-in-transaction waiting for
+        #   this coroutine to return. The database deadlock detector CANNOT
+        #   see this cycle — it manifests as request timeouts, and session1's
+        #   locks block unrelated requests until then.
         await Post.objects.using(session2).create(author_id=user.id)
 
+# Good: join the ambient session when running inside a possibly-active transaction
+async with ctx_session(join_ambient=True) as session:
+    # Reuses the outer session if one exists (no second connection);
+    # creates a new one only at the top level. Lifecycle (commit/rollback/close)
+    # belongs to the outermost owner.
+    await Post.objects.using(session).create(author_id=user.id)
+
 # Bad: No transaction control
 user = await User.objects.create(username="alice")
 # If next operation fails, user is already created

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/03-query-operations-guide.md

@@ -24,7 +24,7 @@ users = await User.objects.filter(
 
 # Comparison operators
 adults = await User.objects.filter(User.age >= 18).all()
-recent = await User.objects.filter(User.created_at > datetime.now() - timedelta(days=7)).all()
+recent = await User.objects.filter(User.created_at > datetime.now(timezone.utc) - timedelta(days=7)).all()
 ```
 
 ### String Operations
@@ -113,18 +113,33 @@ users = await User.objects.annotate(
 
 ### Grouping
 
+Grouped aggregation returns **one row per group**, not model instances — use
+values-mode: list the grouping columns and aggregate aliases in `.values()`.
+
 ```python
-# Group by with aggregation
+# Group by with aggregation → list[dict], one dict per group
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
+# [{"department": "sales", "user_count": 10}, ...]
 
 # Having clause (filter groups)
 large_depts = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").having(func.count() > 10).all()
+).group_by("department").having(func.count() > 10).values("department", "user_count")
+
+# Grouping by the primary key is the one case where .all() stays valid:
+# each group is exactly one model row (e.g. counting related rows per user)
+users = await User.objects.annotate(post_count=Post.id.count()) \
+    .join(Post.__table__, User.id == Post.author_id, join_type="left") \
+    .group_by(User.id).all()
 ```
 
+**Do not** call `.all()` on a query grouped by a non-primary-key column — the
+selected model columns would fall outside GROUP BY, so SQLObjects raises
+`QueryError` instead of silently corrupting the aggregation (each group would
+collapse to a single row).
+
 ### Distinct
 
 ```python
@@ -408,7 +423,7 @@ from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, IntegerColumn, BooleanColumn
 from sqlobjects import Q
 from sqlobjects.expressions import func
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -426,10 +441,10 @@ admins_or_staff = await User.objects.filter(
     Q(User.department == "admin") | Q(User.department == "staff")
 ).all()
 
-# Aggregation
+# Aggregation (one row per group — see "Grouping" section)
 dept_stats = await User.objects.annotate(
     user_count=func.count()
-).group_by("department").all()
+).group_by("department").values("department", "user_count")
 
 # Pagination with field selection
 users = await User.objects.only(

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/04-crud-operations-guide.md

@@ -87,6 +87,32 @@ await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 await User.objects.filter(User.is_active == False).delete()
 ```
 
+### BulkResult (return_objects=True)
+
+`bulk_create` / `bulk_update` / `bulk_delete` return a plain `int` count by default.
+With `return_objects=True` they return a **`BulkResult`**, not a list:
+
+```python
+result = await User.objects.bulk_create(users_data, return_objects=True)
+
+result.objects        # list[User] — or list[dict] when return_fields is given
+result.success_count  # rows written successfully
+result.error_count    # rows that failed
+result.total_count    # input rows (success + failed)
+result.failed_records # list[FailedRecord] with .index/.data/.error per failure
+```
+
+Key semantics:
+
+- **Sequence protocol**: `len(result)`, `for obj in result`, and `result[i]` all
+  operate on `result.objects` (the successfully returned objects).
+- **Partial failure**: `len(result)` can be less than `result.total_count`.
+  Always read `success_count` / `failed_records` when `error_count > 0`.
+- **Order guarantee**: for `bulk_create`, `result.objects` order matches the
+  input rows order.
+- **`return_fields`**: when specified, `objects` contains dicts limited to those
+  fields instead of model instances.
+
 ### Cascade on Delete
 
 Both delete entry points detect and apply cascade behavior automatically:
@@ -126,9 +152,11 @@ users_data = [
 await User.objects.bulk_create(users_data, batch_size=500)
 
 # Bulk update with match fields
+# (bulk rows must be plain values — datetime.now(timezone.utc) here, never naive
+# local time; per-row SQL expressions are not supported in bulk operations)
 mappings = [
-    {"id": 1, "status": "active", "last_seen": datetime.now()},
-    {"id": 2, "status": "inactive", "last_seen": datetime.now()},
+    {"id": 1, "status": "active", "last_seen": datetime.now(timezone.utc)},
+    {"id": 2, "status": "inactive", "last_seen": datetime.now(timezone.utc)},
 ]
 await User.objects.bulk_update(mappings, match_fields=["id"])
 
@@ -137,6 +165,68 @@ user_ids = list(range(1, 1001))
 await User.objects.bulk_delete(user_ids, id_field="id", batch_size=1000)
 ```
 
+## SQL Expressions as Write Values
+
+`create()` and `QuerySet.update()` accept SQLAlchemy expressions as values —
+they are evaluated by the database, not serialized in Python:
+
+```python
+from sqlalchemy import func, text
+
+# Database clock, not application clock
+await Task.objects.filter(Task.id == task_id).update(claimed_at=func.now())
+
+# Relative updates (atomic, no read-modify-write race)
+await User.objects.filter(User.id == user_id).update(age=User.age + 1)
+
+# SQL fragments
+await Task.objects.filter(Task.id == task_id).update(
+    not_before=text("now() + interval '60 seconds'")  # PostgreSQL
+)
+
+# Also works in create()
+task = await Task.objects.create(name="reindex", scheduled_at=func.now())
+```
+
+Notes:
+
+- After `create()` with an expression value, the in-memory instance attribute
+  holds the expression object, not the database result — re-fetch the row if
+  you need the actual stored value.
+- **Bulk operations (`bulk_create` / `bulk_update`) do not support per-row SQL
+  expressions** — they execute with driver-level parameter batching, which
+  requires plain values.
+
+### Clock Discipline
+
+Any field that participates in SQL-side time comparison (scheduling, leases,
+debounce, `not_before` checks) **must use the database clock**, never
+`datetime.now()` from the application:
+
+```python
+# Bad: naive local time — breaks when app timezone != database timezone
+await Task.objects.filter(Task.id == tid).update(not_before=datetime.now())
+
+# Good: database clock — always consistent with SQL-side now() comparisons
+await Task.objects.filter(Task.id == tid).update(not_before=func.now())
+```
+
+A naive `datetime.now()` written from an application in UTC+8 compared against
+PostgreSQL's `now()` (UTC) schedules work 8 hours into the future.
+
+Which clock to use, by scenario:
+
+| Scenario | Correct clock | Example |
+|---|---|---|
+| SQL-compared writes (scheduling, leases, `not_before`) | database clock | `update(not_before=func.now())` |
+| Creation timestamps | database clock via default | `server_default=func.now()` |
+| Instance attributes / signal handlers (need a real value in memory) | aware app clock | `self.updated_at = datetime.now(timezone.utc)` |
+| Bulk operation rows (no per-row SQL expressions) | aware app clock | `{"last_seen": datetime.now(timezone.utc)}` |
+| Read-side window comparisons (relative windows computed in Python) | aware app clock | `filter(created_at >= datetime.now(timezone.utc) - timedelta(days=7))` |
+
+Never naive `datetime.now()` — in every scenario above the naive form breaks
+as soon as the application timezone differs from UTC.
+
 ## Best Practices
 
 ### ✅ Do
@@ -352,7 +442,7 @@ await User.objects.bulk_create(users_data, batch_size=1000)
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, BooleanColumn
 from sqlobjects.session import ctx_session
-from datetime import datetime
+from datetime import datetime, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/05-relationships-guide.md

@@ -132,7 +132,7 @@ posts = await Post.objects.select_related(Post.author).all()
 # Good: Filtered prefetch
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at')
 ).all()
 ```
@@ -350,7 +350,7 @@ posts = await Post.objects.select_related("author").defer(
 # Filter prefetched relationships
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at').limit(10)
 ).all()
 ```
@@ -439,7 +439,7 @@ class Post(ObjectModel):
 ```python
 from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, StringColumn, column, foreign_key, relationship, Related
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -478,7 +478,7 @@ posts = await Post.objects.select_related("author").prefetch_related("comments",
 # Advanced prefetch with filtering
 users = await User.objects.prefetch_related(
     recent_posts=Post.objects.filter(
-        Post.created_at >= datetime.now() - timedelta(days=7)
+        Post.created_at >= datetime.now(timezone.utc) - timedelta(days=7)
     ).order_by('-created_at').limit(5)
 ).all()
 

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/06-validation-signals-guide.md

@@ -58,7 +58,7 @@ class User(ObjectModel):
 ```python
 from sqlobjects.model import ObjectModel
 from sqlobjects.signals import SignalContext
-from datetime import datetime
+from datetime import datetime, timezone
 
 class User(ObjectModel):
     username: Column[str] = StringColumn(length=50)
@@ -69,7 +69,7 @@ class User(ObjectModel):
     # Universal save signals (always triggered)
     async def before_save(self, context: SignalContext):
         """Called before any save operation"""
-        self.updated_at = datetime.now()
+        self.updated_at = datetime.now(timezone.utc)
     
     async def after_save(self, context: SignalContext):
         """Called after any save operation"""
@@ -78,7 +78,7 @@ class User(ObjectModel):
     # Operation-specific signals (triggered based on detected operation)
     async def before_create(self, context: SignalContext):
         """Only triggered for CREATE operations"""
-        self.created_at = datetime.now()
+        self.created_at = datetime.now(timezone.utc)
     
     async def before_update(self, context: SignalContext):
         """Only triggered for UPDATE operations"""
@@ -162,7 +162,7 @@ class User(ObjectModel):
     
     # Good: Fast signal operations
     async def before_save(self, context: SignalContext):
-        self.updated_at = datetime.now()  # Fast
+        self.updated_at = datetime.now(timezone.utc)  # Fast
     
     # Good: Non-critical operations with error handling
     async def after_create(self, context: SignalContext):
@@ -198,7 +198,7 @@ async def before_save(self, context: SignalContext):
 
 # Good: Keep before_save fast, use after_save for heavy operations
 async def before_save(self, context: SignalContext):
-    self.updated_at = datetime.now()  # Fast
+    self.updated_at = datetime.now(timezone.utc)  # Fast
 
 async def after_save(self, context: SignalContext):
     asyncio.create_task(self.process_large_file())  # Background task
@@ -302,7 +302,7 @@ async def after_create(self, context: SignalContext):
 # Background tasks for non-critical operations
 async def after_save(self, context: SignalContext):
     # Critical operations (blocking)
-    self.updated_at = datetime.now()
+    self.updated_at = datetime.now(timezone.utc)
     
     # Non-critical operations (background)
     if not context.is_bulk:
@@ -390,7 +390,7 @@ from sqlobjects.model import ObjectModel
 from sqlobjects.fields import Column, column, StringColumn, IntegerColumn, BooleanColumn
 from sqlobjects.signals import SignalContext
 from sqlobjects.exceptions import ValidationError
-from datetime import datetime
+from datetime import datetime, timezone
 import asyncio
 
 # Custom validators
@@ -420,10 +420,10 @@ class User(ObjectModel):
     
     # Instance signals
     async def before_save(self, context: SignalContext):
-        self.updated_at = datetime.now()
+        self.updated_at = datetime.now(timezone.utc)
     
     async def before_create(self, context: SignalContext):
-        self.created_at = datetime.now()
+        self.created_at = datetime.now(timezone.utc)
     
     async def after_create(self, context: SignalContext):
         try:

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/docs/rules/README.md

@@ -12,6 +12,31 @@ Best practices and usage patterns for SQLObjects, optimized for AI coding assist
 - **[06. Validation & Signals Guide](06-validation-signals-guide.md)** - Data validation and lifecycle hooks
 - **[07. Performance Guide](07-performance-guide.md)** - Optimization techniques and best practices
 
+## Method Ownership Matrix
+
+The single most common mistake is calling a manager-only method on a QuerySet
+(or vice versa). `Model.objects` is the **manager**; `filter()` returns a
+**QuerySet**. They own different methods:
+
+| Operation | Manager (`Model.objects`) | QuerySet (`.filter(...)`) |
+|---|---|---|
+| Create | `create()`, `get_or_create()`, `update_or_create()` | — |
+| Bulk write | `bulk_create()`, `bulk_update()`, `bulk_delete()` | — |
+| Whole-table write | `delete_all()`, `update_all(**values)` | — |
+| Filtered write | — | `update(**values)`, `delete()` |
+| Read | `get()`, `all()`, `first()`, `last()`, `in_bulk()` | `get()`, `all()`, `first()`, `last()` |
+| Refine | `filter()`, `exclude()` (returns QuerySet) | `filter()`, `exclude()`, `order_by()`, `limit()`, `offset()` |
+| Projection | `values()`, `values_list()`, `only()`, `defer()` | `values()`, `values_list()`, `only()`, `defer()` |
+| Aggregate | `count()`, `aggregate()`, `annotate()`, `group_by()`, `having()` | `count()`, `aggregate()`, `annotate()`, `group_by()`, `having()` |
+
+Rules of thumb:
+
+- `filter(...).delete_all()` / `filter(...).update_all()` **do not exist** — a
+  filtered write is `filter(...).delete()` / `filter(...).update(**values)`.
+- `bulk_*` operate on explicit row data, so they live on the manager only.
+- Calling a manager-only method on a QuerySet raises `AttributeError` with a
+  hint pointing to the correct method.
+
 ## Purpose
 
 These rules provide concise, actionable guidance for using SQLObjects effectively. Each guide includes:
@@ -57,4 +82,10 @@ sqlobjects-install-rules kiro     # For Kiro
 
 ## Version
 
-These rules are for SQLObjects 1.0+
+`sqlobjects-install-rules` stamps each installed file with the exact package
+version it was generated from — trust that stamp over this line. Version-
+sensitive behaviors to watch: grouped aggregation (`annotate` + `group_by`)
+raises `QueryError` on out-of-group column selection and returns rows via
+`.values()` since 2.0, and `aggregate()` combined with `group_by()` also
+raises `QueryError` since 2.0; earlier versions silently expanded GROUP BY
+(or dropped it entirely for `aggregate()`) and returned wrong results.

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlobjects"
-version = "1.10.0"
+version = "2.0.1"
 description = "Django-style async ORM library based on SQLAlchemy with chainable queries, Q objects, and relationship loading"
 readme = "README.md"
 license = "MIT"

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/__init__.py

@@ -19,7 +19,7 @@ from .queryset import Q, QuerySet
 from .sql_logging import ObjectLogger, get_caller_frame
 
 
-__version__ = "1.10.0"
+__version__ = "2.0.1"
 
 __all__ = [
     # Core classes

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/_install_rules.py

@@ -5,6 +5,16 @@ import sys
 from pathlib import Path
 
 
+def _get_package_version() -> str:
+    """Get the installed sqlobjects version."""
+    try:
+        from . import __version__
+
+        return __version__
+    except Exception:
+        return "unknown"
+
+
 def find_project_root() -> Path:
     """Find project root by looking for common markers."""
     current = Path.cwd()
@@ -73,13 +83,19 @@ def install_rules(target_name: str, target_dir: Path | None = None) -> bool:
         print(f"Error: Rules directory not found at {rules_dir}", file=sys.stderr)
         return False
 
-    # Create target directory and copy files
+    # Create target directory and copy files, stamping the package version so
+    # AI assistants reading the rules know which behaviors they document
     try:
         target_dir.mkdir(parents=True, exist_ok=True)
 
+        version = _get_package_version()
+        stamp = f"<!-- Generated for SQLObjects {version} — behaviors documented here match this version -->\n\n"
+
         copied_count = 0
         for file in rules_dir.glob("*.md"):
-            shutil.copy2(file, target_dir / file.name)
+            content = file.read_text(encoding="utf-8")
+            (target_dir / file.name).write_text(stamp + content, encoding="utf-8")
+            shutil.copystat(file, target_dir / file.name)
             copied_count += 1
 
         if copied_count > 0:

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/exceptions.py

@@ -20,6 +20,7 @@ __all__ = [
     "ConfigurationError",
     "DeferredFieldError",
     "PrimaryKeyError",
+    "QueryError",
     "SQLError",
     "OperationalError",
     "DataError",
@@ -400,6 +401,23 @@ class PrimaryKeyError(SQLObjectsError):
         super().__init__(message)
 
 
+class QueryError(SQLObjectsError):
+    """Raised when a query is constructed in a way that cannot be executed safely.
+
+    SQLObjects raises this instead of silently rewriting the query semantics —
+    for example when annotated GROUP BY queries select columns outside the
+    grouping columns, which would degenerate every group to a single row.
+
+    Examples:
+        >>> try:
+        ...     await User.objects.annotate(cnt=func.count()).group_by("department").all()
+        ... except QueryError:
+        ...     print("Use .values()/.only() with the grouping columns instead")
+    """
+
+    pass
+
+
 class SQLError(SQLObjectsError):
     """Base class for SQLAlchemy operation errors.
 

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/expressions/terminal.py

@@ -3,8 +3,6 @@
 from datetime import date, datetime
 from typing import TYPE_CHECKING, Any, TypeVar
 
-from sqlalchemy import and_, select
-
 from .base import QueryExpression
 
 
@@ -173,23 +171,19 @@ class ValuesExpression(QueryExpression[list[dict[str, Any]]]):
 
     def get_query(self):
         """Return SQLAlchemy query object."""
-        return self._builder.build(self._builder.model_class.get_table())
+        return self._builder.build(self._builder.model_class.get_table(), values_fields=self._fields)
 
     async def execute(self) -> list[dict[str, Any]]:
         if not self._executor:
             raise RuntimeError("No executor available for values execution")
-        query = self._builder.build(self._builder.model_class.get_table())
-        result = await self._executor.execute(query, "values", fields=self._fields)
+        query = self.get_query()
+        result = await self._executor.execute(query, "values", fields=self._fields, prebuilt=True)
         if isinstance(result, list):
             return [dict(zip(self._fields, row, strict=False)) for row in result]
         return []
 
     def get_sql(self) -> str:
-        table = self._builder.model_class.get_table()
-        columns = [table.c[field] for field in self._fields if field in table.c]
-        query = select(*columns).select_from(table)
-        if hasattr(self._builder, "conditions") and self._builder.conditions:
-            query = query.where(and_(*self._builder.conditions))
+        query = self.get_query()
         return str(query.compile(compile_kwargs={"literal_binds": True}))
 
 
@@ -204,13 +198,13 @@ class ValuesListExpression(QueryExpression[list[Any] | list[tuple[Any, ...]]]):
 
     def get_query(self):
         """Return SQLAlchemy query object."""
-        return self._builder.build(self._builder.model_class.get_table())
+        return self._builder.build(self._builder.model_class.get_table(), values_fields=self._fields)
 
     async def execute(self) -> list[Any] | list[tuple[Any, ...]]:
         if not self._executor:
             raise RuntimeError("No executor available for values_list execution")
-        query = self._builder.build(self._builder.model_class.get_table())
-        result = await self._executor.execute(query, "values_list", fields=list(self._fields))
+        query = self.get_query()
+        result = await self._executor.execute(query, "values_list", fields=list(self._fields), prebuilt=True)
         if isinstance(result, list):
             if self._flat and len(self._fields) == 1:
                 return [row[0] for row in result]
@@ -218,7 +212,7 @@ class ValuesListExpression(QueryExpression[list[Any] | list[tuple[Any, ...]]]):
         return []
 
     def get_sql(self) -> str:
-        query = self._builder.build(self._builder.model_class.get_table())
+        query = self.get_query()
         return str(query.compile(compile_kwargs={"literal_binds": True}))
 
 

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/metadata.py

@@ -595,29 +595,48 @@ class ModelProcessor(type):
         def col_sig(idx):
             return tuple(sorted(col.name for col in idx.columns)) if idx.columns else None
 
-        full_sig_map: dict[tuple, list] = {}  # (cols, unique) -> indexes
+        def dialect_sig(idx):
+            # Dialect kwargs (postgresql_where / postgresql_using / mysql_using, etc.)
+            # are part of an index's identity: same columns with different partial
+            # predicates or access methods are distinct indexes, not duplicates.
+            # Values may be str or SQLAlchemy expressions, so compare via str().
+            # dialect_kwargs only holds explicitly passed args, not dialect defaults.
+            kwargs = getattr(idx, "dialect_kwargs", None) or {}
+            return tuple(sorted((k, str(v)) for k, v in kwargs.items() if v is not None))
+
+        def is_partial(idx):
+            return any(k.endswith("_where") for k, _ in dialect_sig(idx))
+
+        full_sig_map: dict[tuple, list] = {}  # (cols, unique, dialect_sig) -> indexes
         col_map: dict[tuple, list] = {}  # cols -> indexes
 
         for idx in list(table.indexes):
             cs = col_sig(idx)
             if cs is None:
                 continue
-            full_sig_map.setdefault((cs, getattr(idx, "unique", False)), []).append(idx)
+            full_sig_map.setdefault((cs, getattr(idx, "unique", False), dialect_sig(idx)), []).append(idx)
             col_map.setdefault(cs, []).append(idx)
 
         to_remove: set = set()
 
-        # Remove exact duplicates: prefer explicit names over SQLAlchemy auto-generated "ix_*"
+        # Remove exact duplicates (same columns, unique flag, and dialect kwargs):
+        # prefer explicit names over SQLAlchemy auto-generated "ix_*". Sort by name
+        # so the kept index is deterministic regardless of set iteration order.
         for indexes in full_sig_map.values():
             if len(indexes) > 1:
-                explicit = [i for i in indexes if not (i.name and i.name.startswith("ix_"))]
-                keep = explicit[0] if explicit else indexes[0]
+                explicit = sorted(
+                    (i for i in indexes if not (i.name and i.name.startswith("ix_"))),
+                    key=lambda i: i.name or "",
+                )
+                keep = explicit[0] if explicit else sorted(indexes, key=lambda i: i.name or "")[0]
                 to_remove.update(i for i in indexes if i is not keep)
 
-        # Remove non-unique when unique exists on same columns
+        # Remove full-table non-unique when a full-table unique exists on same columns.
+        # Partial indexes (unique or not) never participate: a partial unique index
+        # only covers rows matching its predicate and cannot replace a full index.
         for indexes in col_map.values():
-            if any(getattr(i, "unique", False) for i in indexes):
-                to_remove.update(i for i in indexes if not getattr(i, "unique", False))
+            if any(getattr(i, "unique", False) and not is_partial(i) for i in indexes):
+                to_remove.update(i for i in indexes if not getattr(i, "unique", False) and not is_partial(i))
 
         for idx in to_remove:
             table.indexes.discard(idx)

{sqlobjects-1.10.0 → sqlobjects-2.0.1}/sqlobjects/mixins.py

@@ -266,6 +266,12 @@ class ValidationMixin(PrimaryKeyMixin):
             )
             if validators:
                 value = getattr(self, field_name, None)
+                # SQL expressions (func.now(), text(...), column arithmetic) are
+                # evaluated by the database — Python-side validators don't apply
+                from sqlalchemy.sql import ClauseElement
+
+                if isinstance(value, ClauseElement):
+                    return
                 try:
                     from .validators import validate_field_value