feat: add SQLModel compatibility (#686)

- **SQLModel `table=True` models** now work seamlessly with Advanced Alchemy repositories and services without requiring AA base classes
- `ModelProtocol` no longer requires `to_dict()` — models only need `__mapper__`, `__table__`, and `__name__` (which all SQLAlchemy-mapped models have)
- New `model_to_dict()` utility converts any mapped model to a dict using mapper column introspection
- `is_schema()` family of functions now correctly **exclude** SQLModel table models (they are ORM models, not transfer schemas)
- `schema_dump()` returns SQLModel table instances as-is instead of calling `model_dump()`
- New `is_sqlmodel_table_model()` detection function

Author: cofin

.pre-commit-config.yaml

@@ -22,7 +22,7 @@ repos:
       - id: unasyncd
         additional_dependencies: ["ruff"]
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.15.2"
+    rev: "v0.15.5"
     hooks:
       # Run the linter.
       - id: ruff
@@ -32,7 +32,7 @@ repos:
       - id: ruff-format
         types_or: [python, pyi]
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         additional_dependencies: [tomli]

README.md

@@ -36,6 +36,10 @@ offering:
 - Integration with major web frameworks including Litestar, Starlette, FastAPI, Sanic
 - Custom-built alembic configuration and CLI with optional framework integration
 - Utility base classes with audit columns, primary keys and utility functions
+- [SQLModel](https://sqlmodel.tiangolo.com/) compatibility — use `SQLModel` `table=True` models directly with repositories and services
+- Composite primary key support — work with multi-column primary keys across repositories, services, and bulk operations
+- Read/write replica routing with automatic query routing, round-robin/random replica selection, and sticky-primary mode
+- Dogpile caching integration for query result caching
 - Built in `File Object` data type for storing objects:
     - Unified interface for various storage backends ([`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) and [`obstore`](https://developmentseed.org/obstore/latest/))
     - Optional lifecycle event hooks integrated with SQLAlchemy's event system to automatically save and delete files as records are inserted, updated, or deleted.
@@ -49,7 +53,7 @@ offering:
 - Synchronous and asynchronous repositories featuring:
     - Common CRUD operations for SQLAlchemy models
     - Bulk inserts, updates, upserts, and deletes with dialect-specific enhancements
-    - Integrated counts, pagination, sorting, filtering with `LIKE`, `IN`, and dates before and/or after.
+    - Integrated counts, pagination, sorting, filtering with `LIKE`, `IN`, `IS NULL`/`IS NOT NULL`, and dates before and/or after.
 - Tested support for multiple database backends including:
     - SQLite via [aiosqlite](https://aiosqlite.omnilib.dev/en/stable/) or [sqlite](https://docs.python.org/3/library/sqlite3.html)
     - Postgres via [asyncpg](https://magicstack.github.io/asyncpg/current/) or [psycopg3 (async or sync)](https://www.psycopg.org/psycopg3/)

advanced_alchemy/_typing.py

@@ -0,0 +1,45 @@
+# ruff: noqa: RUF100
+"""Foundational type shims for optional dependencies.
+
+Provides stub types used across the package when optional libraries
+(e.g. SQLModel) are not installed.  This module is intentionally
+kept minimal and free of internal imports so that low-level modules
+like ``base`` can use it without reaching into higher-level packages.
+"""
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from sqlalchemy.orm import Mapper
+    from sqlalchemy.sql import FromClause
+
+
+class SQLModelBaseLike:
+    """Placeholder for sqlmodel.SQLModel when the package is not installed.
+
+    Declares the same structural attributes as :class:`ModelProtocol`
+    so that type checkers can see SQLModel ``table=True`` models as
+    protocol-compatible without requiring the real SQLModel package.
+    """
+
+    if TYPE_CHECKING:
+        __table__: "FromClause"
+        __mapper__: "Mapper[Any]"
+        __name__: str
+
+    model_fields: ClassVar[dict[str, Any]] = {}
+
+
+try:
+    from sqlmodel import SQLModel as SQLModelBase
+
+    SQLMODEL_INSTALLED: bool = True  # pyright: ignore[reportConstantRedefinition]
+except ImportError:
+    SQLModelBase = SQLModelBaseLike  # type: ignore[assignment,misc]
+    SQLMODEL_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
+__all__ = (
+    "SQLMODEL_INSTALLED",
+    "SQLModelBase",
+    "SQLModelBaseLike",
+)

advanced_alchemy/alembic/utils.py

@@ -5,6 +5,7 @@
 from sqlalchemy import Column, Engine, MetaData, String, Table
 from typing_extensions import TypeIs
 
+from advanced_alchemy.base import model_to_dict
 from advanced_alchemy.exceptions import MissingDependencyError
 from advanced_alchemy.utils.sync_tools import async_
 
@@ -114,7 +115,7 @@ def _dump_table_sync(session: "AbstractContextManager[Session]") -> None:
                     (SQLAlchemySyncRepository,),
                     exec_body=lambda ns, model=model: ns.setdefault("model_type", model),  # type: ignore[misc]
                 )
-                json_path.write_text(encode_json([row.to_dict() for row in repo(session=_session).list()]))
+                json_path.write_text(encode_json([model_to_dict(row) for row in repo(session=_session).list()]))
 
     async def _dump_table_async(session: "AbstractAsyncContextManager[AsyncSession]") -> None:
         from advanced_alchemy.repository import SQLAlchemyAsyncRepository
@@ -132,7 +133,7 @@ async def _dump_table_async(session: "AbstractAsyncContextManager[AsyncSession]"
                     (SQLAlchemyAsyncRepository,),
                     exec_body=lambda ns, model=model: ns.setdefault("model_type", model),  # type: ignore[misc]
                 )
-                json_path.write_text(encode_json([row.to_dict() for row in await repo(session=_session).list()]))
+                json_path.write_text(encode_json([model_to_dict(row) for row in await repo(session=_session).list()]))
 
     await async_(dump_dir.mkdir)(exist_ok=True)
 

advanced_alchemy/base.py

@@ -12,6 +12,7 @@
 from sqlalchemy.orm import (
     DeclarativeBase,
     Mapper,
+    class_mapper,
     declared_attr,
 )
 from sqlalchemy.orm import (
@@ -72,6 +73,7 @@
     "create_registry",
     "merge_table_arguments",
     "metadata_registry",
+    "model_to_dict",
     "orm_registry",
     "table_name_regexp",
 )
@@ -143,6 +145,9 @@ def merge_table_arguments(cls: type[DeclarativeBase], table_args: Optional[Table
 class ModelProtocol(Protocol):
     """The base SQLAlchemy model protocol.
 
+    Defines the minimal contract for a SQLAlchemy-mapped model. Any class with
+    a mapper and table (including SQLModel ``table=True`` models) satisfies this protocol.
+
     Attributes:
         __table__ (:class:`sqlalchemy.sql.FromClause`): The table associated with the model.
         __mapper__ (:class:`sqlalchemy.orm.Mapper`): The mapper for the model.
@@ -154,13 +159,37 @@ class ModelProtocol(Protocol):
         __mapper__: Mapper[Any]
         __name__: str
 
-    def to_dict(self, exclude: Optional[set[str]] = None) -> dict[str, Any]:
-        """Convert model to dictionary.
 
-        Returns:
-            Dict[str, Any]: A dict representation of the model
-        """
-        ...
+def model_to_dict(instance: "ModelProtocol", exclude: Optional[set[str]] = None) -> dict[str, Any]:
+    """Convert a mapped model instance to a dictionary.
+
+    Works with any SQLAlchemy-mapped model, including:
+    - Advanced Alchemy models (delegates to ``to_dict()``)
+    - SQLModel ``table=True`` models (uses mapper-based column iteration)
+    - Any other mapped class
+
+    Args:
+        instance: A SQLAlchemy-mapped model instance.
+        exclude: Optional set of field names to exclude from the output.
+
+    Returns:
+        A dictionary of column names to values.
+    """
+    to_dict_fn = getattr(instance, "to_dict", None)
+    if to_dict_fn is not None and callable(to_dict_fn):
+        return to_dict_fn(exclude=exclude)  # type: ignore[no-any-return]
+
+    exclude_fields: set[str] = {"sa_orm_sentinel", "_sentinel"}
+    with contextlib.suppress(AttributeError):
+        exclude_fields = exclude_fields.union(cast("set[str]", instance._sa_instance_state.unloaded))  # type: ignore[attr-defined,union-attr]  # noqa: SLF001
+    if exclude:
+        exclude_fields = exclude_fields.union(exclude)
+    mapper = class_mapper(type(instance))
+    return {
+        field: getattr(instance, field)
+        for field in mapper.columns.keys()  # noqa: SIM118
+        if field not in exclude_fields
+    }
 
 
 class BasicAttributes:

advanced_alchemy/repository/_async.py

@@ -45,6 +45,7 @@
 from sqlalchemy.sql.dml import ReturningDelete, ReturningUpdate
 from sqlalchemy.sql.selectable import ForUpdateArg, ForUpdateParameter
 
+from advanced_alchemy.base import model_to_dict
 from advanced_alchemy.exceptions import ErrorMessages, NotFoundError, RepositoryError, wrap_sqlalchemy_exception
 from advanced_alchemy.filters import StatementFilter, StatementTypeT
 from advanced_alchemy.repository._util import (
@@ -2351,10 +2352,7 @@ async def update_many(
         supports_updated_at = hasattr(self.model_type, "updated_at")
         data_to_update: List[dict[str, Any]] = []
         for v in data:
-            if isinstance(v, self.model_type) or (hasattr(v, "to_dict") and callable(v.to_dict)):
-                update_payload = v.to_dict()
-            else:
-                update_payload = cast("dict[str, Any]", schema_dump(v))
+            update_payload = model_to_dict(v) if hasattr(v, "__mapper__") else schema_dump(cast("dict[str, Any]", v))
 
             if supports_updated_at and (update_payload.get("updated_at") is None):
                 update_payload["updated_at"] = datetime.datetime.now(datetime.timezone.utc)
@@ -2824,7 +2822,7 @@ async def upsert(
         else:
             # Exclude all PK columns when matching by non-PK fields
             exclude_cols = set(self._pk_attr_names) if self.has_composite_pk else {self.id_attribute}
-            match_filter = data.to_dict(exclude=exclude_cols)
+            match_filter = model_to_dict(data, exclude=exclude_cols)
         existing = await self.get_one_or_none(
             load=load, execution_options=execution_options, bind_group=bind_group, **match_filter
         )
@@ -2841,7 +2839,7 @@ async def upsert(
         ):
             # Exclude all PK columns when copying field values
             exclude_cols = set(self._pk_attr_names) if self.has_composite_pk else {self.id_attribute}
-            for field_name, new_field_value in data.to_dict(exclude=exclude_cols).items():
+            for field_name, new_field_value in model_to_dict(data, exclude=exclude_cols).items():
                 field = getattr(existing, field_name, MISSING)
                 if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)

advanced_alchemy/repository/_sync.py

@@ -46,6 +46,7 @@
 from sqlalchemy.sql.dml import ReturningDelete, ReturningUpdate
 from sqlalchemy.sql.selectable import ForUpdateArg, ForUpdateParameter
 
+from advanced_alchemy.base import model_to_dict
 from advanced_alchemy.exceptions import ErrorMessages, NotFoundError, RepositoryError, wrap_sqlalchemy_exception
 from advanced_alchemy.filters import StatementFilter, StatementTypeT
 from advanced_alchemy.repository._util import (
@@ -2346,10 +2347,7 @@ def update_many(
         supports_updated_at = hasattr(self.model_type, "updated_at")
         data_to_update: List[dict[str, Any]] = []
         for v in data:
-            if isinstance(v, self.model_type) or (hasattr(v, "to_dict") and callable(v.to_dict)):
-                update_payload = v.to_dict()
-            else:
-                update_payload = cast("dict[str, Any]", schema_dump(v))
+            update_payload = model_to_dict(v) if hasattr(v, "__mapper__") else schema_dump(cast("dict[str, Any]", v))
 
             if supports_updated_at and (update_payload.get("updated_at") is None):
                 update_payload["updated_at"] = datetime.datetime.now(datetime.timezone.utc)
@@ -2817,7 +2815,7 @@ def upsert(
         else:
             # Exclude all PK columns when matching by non-PK fields
             exclude_cols = set(self._pk_attr_names) if self.has_composite_pk else {self.id_attribute}
-            match_filter = data.to_dict(exclude=exclude_cols)
+            match_filter = model_to_dict(data, exclude=exclude_cols)
         existing = self.get_one_or_none(
             load=load, execution_options=execution_options, bind_group=bind_group, **match_filter
         )
@@ -2834,7 +2832,7 @@ def upsert(
         ):
             # Exclude all PK columns when copying field values
             exclude_cols = set(self._pk_attr_names) if self.has_composite_pk else {self.id_attribute}
-            for field_name, new_field_value in data.to_dict(exclude=exclude_cols).items():
+            for field_name, new_field_value in model_to_dict(data, exclude=exclude_cols).items():
                 field = getattr(existing, field_name, MISSING)
                 if field is not MISSING and not compare_values(field, new_field_value):  # pragma: no cover
                     setattr(existing, field_name, new_field_value)

advanced_alchemy/service/__init__.py

@@ -50,6 +50,7 @@
     is_schema_or_dict_without_field,
     is_schema_with_field,
     is_schema_without_field,
+    is_sqlmodel_table_model,
     schema_dump,
 )
 
@@ -99,6 +100,7 @@
     "is_schema_or_dict_without_field",
     "is_schema_with_field",
     "is_schema_without_field",
+    "is_sqlmodel_table_model",
     "model_from_dict",
     "schema_dump",
 )

advanced_alchemy/service/_async.py

@@ -18,6 +18,7 @@
 from sqlalchemy.sql.selectable import ForUpdateParameter
 from typing_extensions import Self
 
+from advanced_alchemy.base import ModelProtocol, model_to_dict
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig
 from advanced_alchemy.exceptions import AdvancedAlchemyError, ErrorMessages, ImproperConfigurationError, RepositoryError
 from advanced_alchemy.filters import StatementFilter
@@ -39,6 +40,7 @@
     is_dto_data,
     is_msgspec_struct,
     is_pydantic_model,
+    is_sqlmodel_table_model,
 )
 from advanced_alchemy.utils.dataclass import Empty, EmptyType
 
@@ -477,8 +479,12 @@ async def to_model(
         }
         if operation and (op := operation_map.get(operation)):
             data = await op(data)
+        if isinstance(data, self.model_type):
+            return data
         if is_dict(data):
             return model_from_dict(self.model_type, **data)
+        if is_sqlmodel_table_model(data):
+            return model_from_dict(self.model_type, **model_to_dict(cast("ModelProtocol", data)))
         if is_pydantic_model(data):
             return model_from_dict(
                 self.model_type,
@@ -1092,7 +1098,7 @@ async def get_or_upsert(
                 execution_options=execution_options,
                 uniquify=self._get_uniquify(uniquify),
                 bind_group=bind_group,
-                **validated_model.to_dict(),
+                **model_to_dict(validated_model),
             ),
         )
 
@@ -1154,7 +1160,7 @@ async def get_and_update(
                 execution_options=execution_options,
                 uniquify=self._get_uniquify(uniquify),
                 bind_group=bind_group,
-                **validated_model.to_dict(),
+                **model_to_dict(validated_model),
             ),
         )
 

advanced_alchemy/service/_sync.py

@@ -19,6 +19,7 @@
 from sqlalchemy.sql.selectable import ForUpdateParameter
 from typing_extensions import Self
 
+from advanced_alchemy.base import ModelProtocol, model_to_dict
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig
 from advanced_alchemy.exceptions import AdvancedAlchemyError, ErrorMessages, ImproperConfigurationError, RepositoryError
 from advanced_alchemy.filters import StatementFilter
@@ -38,6 +39,7 @@
     is_dto_data,
     is_msgspec_struct,
     is_pydantic_model,
+    is_sqlmodel_table_model,
 )
 from advanced_alchemy.utils.dataclass import Empty, EmptyType
 
@@ -476,8 +478,12 @@ def to_model(
         }
         if operation and (op := operation_map.get(operation)):
             data = op(data)
+        if isinstance(data, self.model_type):
+            return data
         if is_dict(data):
             return model_from_dict(self.model_type, **data)
+        if is_sqlmodel_table_model(data):
+            return model_from_dict(self.model_type, **model_to_dict(cast("ModelProtocol", data)))
         if is_pydantic_model(data):
             return model_from_dict(
                 self.model_type,
@@ -1091,7 +1097,7 @@ def get_or_upsert(
                 execution_options=execution_options,
                 uniquify=self._get_uniquify(uniquify),
                 bind_group=bind_group,
-                **validated_model.to_dict(),
+                **model_to_dict(validated_model),
             ),
         )
 
@@ -1153,7 +1159,7 @@ def get_and_update(
                 execution_options=execution_options,
                 uniquify=self._get_uniquify(uniquify),
                 bind_group=bind_group,
-                **validated_model.to_dict(),
+                **model_to_dict(validated_model),
             ),
         )