sqlmodel-ext 0.3.5__tar.gz → 0.4.1__tar.gz

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlmodel-ext
-Version: 0.3.5
+Version: 0.4.1
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext
@@ -24,7 +24,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: pydantic>=2.0
 Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: sqlmodel>=0.0.32
 Provides-Extra: cache
 Requires-Dist: orjson>=3.0; extra == 'cache'
 Requires-Dist: redis>=5.0; extra == 'cache'
@@ -70,7 +70,7 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 | **RelationPreloadMixin** | Decorator-based automatic relationship preloading (prevents `MissingGreenlet` errors) |
 | **ListResponse[T]** | Generic paginated response model for list endpoints |
 | **Field Types** | Reusable constrained types: `Str64`, `Port`, `IPAddress`, `HttpUrl`, `SafeHttpUrl`, and more |
-| **PostgreSQL Types** | `Array[T]` for native ARRAY, `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
+| **PostgreSQL Types** | `Array[T]` for native ARRAY (read-tolerant for enum arrays during rolling-deploy version skew), `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
 | **Info Response DTOs** | Pre-built mixins for API response models with id/timestamp fields |
 
 ## Installation
@@ -108,12 +108,13 @@ pip install sqlmodel-ext[pgvector]
 ### Define Models
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # requires: pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base class -- fields only, no database table
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # user-visible name: rejects "" and whitespace-only
+    email: EmailStr
 
 # Table class -- inherits fields + gains async CRUD + UUID primary key
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -438,17 +439,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── Polymorphic models ────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -457,13 +460,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -493,15 +496,15 @@ These mixins provide the async CRUD interface. `TableBaseMixin` uses an auto-inc
 Both mixins automatically add `id`, `created_at`, and `updated_at` fields.
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # Integer primary key
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID primary key (recommended for most use cases)
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- Batch Insert
@@ -529,7 +532,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # Save with relationship preloading
-user = await user.save(session, load=User.profile)
+# (rel() casts the Relationship field for type checkers, which would
+#  otherwise infer User.profile as Profile instead of a loadable attribute)
+user = await user.save(session, load=rel(User.profile))
 
 # Save with optimistic lock retry
 user = await user.save(session, optimistic_retry_count=3)
@@ -562,9 +567,10 @@ user3 = await user3.save(session)        # commits all three
 #### `update()` -- Partial Update from a Model
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional auto-converts every inherited field to ``T | None = None``
+# while preserving constraints -- no hand-written Optional boilerplate
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # Only updates fields that were explicitly set
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -643,7 +649,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # With JOIN
@@ -767,11 +773,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base class (fields only, no table)
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. Abstract parent (creates the parent table)
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -783,13 +790,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. Concrete subclasses (each gets its own table)
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -823,16 +830,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # Added to userfile table as nullable
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # Added to userfile table as nullable
+    file_size: NonNegativeBigInt | None = None  # Added to userfile table as nullable
 
 # After all models are defined, before configure_mappers():
 register_sti_columns_for_all_subclasses()
@@ -858,7 +866,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # Loads all subclass-specific columns
 )
 ```
@@ -885,15 +893,22 @@ Tool._is_joined_table_inheritance()  # True for JTI, False for STI
 Prevents lost updates in concurrent environments using SQLAlchemy's `version_id_col` mechanism.
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin MUST come before TableBaseMixin in MRO
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 The mixin adds a `version` integer field (starting at 0). Every `UPDATE` generates SQL like:
@@ -945,11 +960,11 @@ The `RelationPreloadMixin` and `@requires_relations` decorator automatically loa
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()
@@ -1391,29 +1406,53 @@ When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQ
 
 ```python
 class UserBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
     """User display name"""     # ← parsed by Pydantic
 
 class UserUpdateRequest(UserBase, all_fields_optional=True):
     pass
-    # name: str | None = None   — description "User display name" is automatically inherited
+    # name: NonEmptyStrippedStr64 | None = None — description "User display name" is inherited
     # Shows up correctly in OpenAPI/Swagger docs
 ```
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1430,7 +1469,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError

{sqlmodel_ext-0.3.5 → sqlmodel_ext-0.4.1}/README.md

@@ -25,7 +25,7 @@ Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphi
 | **RelationPreloadMixin** | Decorator-based automatic relationship preloading (prevents `MissingGreenlet` errors) |
 | **ListResponse[T]** | Generic paginated response model for list endpoints |
 | **Field Types** | Reusable constrained types: `Str64`, `Port`, `IPAddress`, `HttpUrl`, `SafeHttpUrl`, and more |
-| **PostgreSQL Types** | `Array[T]` for native ARRAY, `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
+| **PostgreSQL Types** | `Array[T]` for native ARRAY (read-tolerant for enum arrays during rolling-deploy version skew), `JSON100K`/`JSONList100K` for size-limited JSONB, `NumpyVector` for pgvector+NumPy |
 | **Info Response DTOs** | Pre-built mixins for API response models with id/timestamp fields |
 
 ## Installation
@@ -63,12 +63,13 @@ pip install sqlmodel-ext[pgvector]
 ### Define Models
 
 ```python
-from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, Str64
+from pydantic import EmailStr  # requires: pip install 'pydantic[email]'
+from sqlmodel_ext import SQLModelBase, UUIDTableBaseMixin, NonEmptyStrippedStr64
 
 # Base class -- fields only, no database table
 class UserBase(SQLModelBase):
-    name: Str64
-    email: str
+    name: NonEmptyStrippedStr64   # user-visible name: rejects "" and whitespace-only
+    email: EmailStr
 
 # Table class -- inherits fields + gains async CRUD + UUID primary key
 class User(UserBase, UUIDTableBaseMixin, table=True):
@@ -393,17 +394,19 @@ async def delete_article(session: SessionDep, article_id: UUID) -> None:
 
 ```python
 from abc import ABC, abstractmethod
+from pydantic import EmailStr
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin, create_subclass_id_mixin,
     ListResponse, TableViewRequest,
+    Str512, Text1K,
 )
 
 # ── Polymorphic models ────────────────────────────────────────────
 
 class NotificationBase(SQLModelBase):
     user_id: UUID = Field(foreign_key='user.id')
-    message: str
+    message: Text1K
 
 class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
     @abstractmethod
@@ -412,13 +415,13 @@ class Notification(NotificationBase, UUIDTableBaseMixin, PolymorphicBaseMixin, A
 NotifSubclassId = create_subclass_id_mixin('notification')
 
 class EmailNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    email_to: str
+    email_to: EmailStr
 
     def summary(self) -> str:
         return f"Email to {self.email_to}: {self.message}"
 
 class PushNotification(NotifSubclassId, Notification, AutoPolymorphicIdentityMixin, table=True):
-    device_token: str
+    device_token: Str512
 
     def summary(self) -> str:
         return f"Push to {self.device_token}: {self.message}"
@@ -448,15 +451,15 @@ These mixins provide the async CRUD interface. `TableBaseMixin` uses an auto-inc
 Both mixins automatically add `id`, `created_at`, and `updated_at` fields.
 
 ```python
-from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin
+from sqlmodel_ext import SQLModelBase, TableBaseMixin, UUIDTableBaseMixin, NonEmptyStrippedStr64, Text1K
 
 # Integer primary key
 class LogEntry(SQLModelBase, TableBaseMixin, table=True):
-    message: str
+    message: Text1K
 
 # UUID primary key (recommended for most use cases)
 class Project(SQLModelBase, UUIDTableBaseMixin, table=True):
-    name: str
+    name: NonEmptyStrippedStr64
 ```
 
 #### `add()` -- Batch Insert
@@ -484,7 +487,9 @@ user = await User.add(session, User(name="Alice", email="a@x.com"))
 user = await user.save(session)
 
 # Save with relationship preloading
-user = await user.save(session, load=User.profile)
+# (rel() casts the Relationship field for type checkers, which would
+#  otherwise infer User.profile as Profile instead of a loadable attribute)
+user = await user.save(session, load=rel(User.profile))
 
 # Save with optimistic lock retry
 user = await user.save(session, optimistic_retry_count=3)
@@ -517,9 +522,10 @@ user3 = await user3.save(session)        # commits all three
 #### `update()` -- Partial Update from a Model
 
 ```python
-class UserUpdate(SQLModelBase):
-    name: str | None = None
-    email: str | None = None
+# all_fields_optional auto-converts every inherited field to ``T | None = None``
+# while preserving constraints -- no hand-written Optional boilerplate
+class UserUpdate(UserBase, all_fields_optional=True):
+    pass
 
 # Only updates fields that were explicitly set
 user = await user.update(session, UserUpdate(name="Charlie"))
@@ -598,7 +604,7 @@ users = await User.get(session, fetch_mode="all")
 user = await User.get(
     session,
     User.id == user_id,
-    load=[User.profile, User.orders],
+    load=[rel(User.profile), rel(User.orders)],
 )
 
 # With JOIN
@@ -722,11 +728,12 @@ from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     create_subclass_id_mixin,
+    HttpUrl, NonEmptyStrippedStr64, NonNegativeInt,
 )
 
 # 1. Base class (fields only, no table)
 class ToolBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
 
 # 2. Abstract parent (creates the parent table)
 class Tool(ToolBase, UUIDTableBaseMixin, PolymorphicBaseMixin, ABC):
@@ -738,13 +745,13 @@ ToolSubclassIdMixin = create_subclass_id_mixin('tool')
 
 # 4. Concrete subclasses (each gets its own table)
 class WebSearchTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    search_url: str
+    search_url: HttpUrl
 
     async def execute(self) -> str:
         return f"Searching {self.search_url}"
 
 class CalculatorTool(ToolSubclassIdMixin, Tool, AutoPolymorphicIdentityMixin, table=True):
-    precision: int = 2
+    precision: NonNegativeInt = 2
 
     async def execute(self) -> str:
         return "Calculating..."
@@ -778,16 +785,17 @@ from sqlmodel_ext import (
     PolymorphicBaseMixin, AutoPolymorphicIdentityMixin,
     register_sti_columns_for_all_subclasses,
     register_sti_column_properties_for_all_subclasses,
+    NonNegativeBigInt, Str256,
 )
 
 class UserFile(SQLModelBase, UUIDTableBaseMixin, PolymorphicBaseMixin, table=True):
-    filename: str
+    filename: Str256
 
 class PendingFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
     upload_deadline: datetime | None = None  # Added to userfile table as nullable
 
 class CompletedFile(UserFile, AutoPolymorphicIdentityMixin, table=True):
-    file_size: int | None = None  # Added to userfile table as nullable
+    file_size: NonNegativeBigInt | None = None  # Added to userfile table as nullable
 
 # After all models are defined, before configure_mappers():
 register_sti_columns_for_all_subclasses()
@@ -813,7 +821,7 @@ class ToolSet(SQLModelBase, UUIDTableBaseMixin, table=True):
 tool_set = await ToolSet.get(
     session,
     ToolSet.id == ts_id,
-    load=ToolSet.tools,
+    load=rel(ToolSet.tools),
     jti_subclasses='all',  # Loads all subclass-specific columns
 )
 ```
@@ -840,15 +848,22 @@ Tool._is_joined_table_inheritance()  # True for JTI, False for STI
 Prevents lost updates in concurrent environments using SQLAlchemy's `version_id_col` mechanism.
 
 ```python
+from enum import StrEnum
+
 from sqlmodel_ext import (
     SQLModelBase, UUIDTableBaseMixin,
     OptimisticLockMixin, OptimisticLockError,
+    NonNegativeDecimal38_18,
 )
 
+class OrderStatusEnum(StrEnum):
+    pending = 'pending'
+    paid = 'paid'
+
 # OptimisticLockMixin MUST come before TableBaseMixin in MRO
 class Order(OptimisticLockMixin, UUIDTableBaseMixin, table=True):
-    status: str
-    amount: int
+    status: OrderStatusEnum = OrderStatusEnum.pending
+    amount: NonNegativeDecimal38_18
 ```
 
 The mixin adds a `version` integer field (starting at 0). Every `UPDATE` generates SQL like:
@@ -900,11 +915,11 @@ The `RelationPreloadMixin` and `@requires_relations` decorator automatically loa
 
 ```python
 from sqlmodel import Relationship
-from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase
+from sqlmodel_ext import UUIDTableBaseMixin, SQLModelBase, NonNegativeDecimal38_18
 from sqlmodel_ext.mixins import RelationPreloadMixin, requires_relations
 
 class GeneratorConfig(SQLModelBase, UUIDTableBaseMixin, table=True):
-    price: int
+    price: NonNegativeDecimal38_18
 
 class Generator(SQLModelBase, UUIDTableBaseMixin, table=True):
     config: GeneratorConfig = Relationship()
@@ -1346,29 +1361,53 @@ When using Pydantic's `use_attribute_docstrings=True` (enabled by default in `SQ
 
 ```python
 class UserBase(SQLModelBase):
-    name: str
+    name: NonEmptyStrippedStr64
     """User display name"""     # ← parsed by Pydantic
 
 class UserUpdateRequest(UserBase, all_fields_optional=True):
     pass
-    # name: str | None = None   — description "User display name" is automatically inherited
+    # name: NonEmptyStrippedStr64 | None = None — description "User display name" is inherited
     # Shows up correctly in OpenAPI/Swagger docs
 ```
 
 ---
 
-### safe_reset
+### Enhanced AsyncSession (cache-aware commit/reset/refresh)
 
-Safely reset an async session, clearing both the DB connection and FOR UPDATE lock tracking:
+`sqlmodel_ext.AsyncSession` subclasses sqlmodel's `AsyncSession` and makes cache
+correctness automatic. Point your session factory at it:
 
 ```python
-from sqlmodel_ext import safe_reset
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from sqlmodel_ext import AsyncSession
 
-# In long-lived tasks (e.g. background workers) between operations:
-await safe_reset(session)
+session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=True)
 ```
 
-This prevents stale `FOR UPDATE` lock tracking in `session.info` when Python reuses object IDs across `reset()` cycles.
+What it does:
+
+- **`commit()`** auto-registers every `CachedTableBaseMixin` mutation in the
+  session (including bare `session.add()` / attribute mutation /
+  `session.delete()` paths) and synchronously invalidates the Redis cache after
+  commit — no more "forgot the cache-aware commit" stale windows.
+- **`reset()`** releases the connection and clears FOR UPDATE lock tracking +
+  cache-invalidation tracking from `session.info` (replaces the removed
+  `safe_reset()` helper — just call `await session.reset()`).
+- **`refresh()`** routes whole-object refreshes of cached models through
+  `Model.get()` (Redis hit + STI polymorphic columns) instead of a raw DB query.
+- **`execute()`** warns when a bare `UPDATE`/`DELETE` hits a cached table
+  without registered invalidation.
+
+Models that don't use `CachedTableBaseMixin` are unaffected — every hook
+degrades to upstream behavior.
+
+> **Breaking change in 0.4.0**: `safe_reset()` and
+> `CachedTableBaseMixin.cache_aware_commit()` were removed. CRUD methods no
+> longer invalidate the cache themselves; invalidation now happens inside
+> `AsyncSession.commit()`. If you use `CachedTableBaseMixin`, you **must**
+> construct sessions with `class_=sqlmodel_ext.AsyncSession` (plain sessions
+> fall back to the fire-and-forget `after_commit` compensation hook, which
+> reintroduces a brief stale-cache window).
 
 ---
 
@@ -1385,7 +1424,7 @@ sqlmodel_ext/
     pagination.py            # ListResponse, TimeFilterRequest, PaginationRequest, TableViewRequest
     mixins/
         __init__.py          # Mixin re-exports
-        table.py             # TableBaseMixin, UUIDTableBaseMixin, safe_reset (async CRUD)
+        table.py             # TableBaseMixin, UUIDTableBaseMixin (async CRUD)
         cached_table.py      # CachedTableBaseMixin (two-tier Redis cache with version invalidation)
         polymorphic.py       # PolymorphicBaseMixin, AutoPolymorphicIdentityMixin, create_subclass_id_mixin
         optimistic_lock.py   # OptimisticLockMixin, OptimisticLockError