feat: repository enhancements and MySQL SQLAlchemy support

.github/workflows/test.yaml

@@ -58,6 +58,11 @@ jobs:
         run: |
           source $VENV
           pytest
+      - name: Test Database Backends
+        if: ${{ !inputs.coverage }}
+        run: |
+          source $VENV
+          pytest -m='sqlalchemy_asyncmy or sqlalchemy_asyncpg'
       - name: Test with coverage
         if: inputs.coverage
         run: poetry run pytest docs/examples tests --cov=litestar --cov-report=xml

.pre-commit-config.yaml

@@ -54,6 +54,7 @@ repos:
           [
             aiosqlite,
             async_timeout,
+            asyncmy,
             asyncpg,
             attrs,
             beanie,
@@ -77,7 +78,7 @@ repos:
             piccolo,
             picologging,
             pydantic,
-            polyfactory,
+            polyfactory==2.0.0a1,
             pytest,
             pytest-lazy-fixture,
             pytest-mock,
@@ -107,6 +108,7 @@ repos:
           [
             aiosqlite,
             async_timeout,
+            asyncmy,
             asyncpg,
             attrs,
             beanie,
@@ -130,7 +132,7 @@ repos:
             piccolo,
             picologging,
             pydantic,
-            polyfactory,
+            polyfactory==2.0.0a1,
             pytest,
             pytest-lazy-fixture,
             pytest-mock,

Makefile

@@ -16,10 +16,16 @@ docs-test:
 test-examples:
 	pytest docs/examples
 
+test-sqlalchemy-asyncpg:
+	pytest tests -m='sqlalchemy_asyncpg'
+
+test-sqlalchemy-asyncmy:
+	pytest tests -m='sqlalchemy_asyncmy'
+
 test:
 	pytest tests
 
-test-all: test test-examples
+test-all: test test-sqlalchemy-asyncpg test-sqlalchemy-asyncmy test-examples
 
 coverage:
 	pytest tests --cov=litestar

docs/conf.py

@@ -70,12 +70,31 @@
     ("py:class", "sqlalchemy.orm.decl_api.DeclarativeMeta"),
     ("py:class", "sqlalchemy.sql.sqltypes.TupleType"),
     ("py:class", "sqlalchemy.dialects.postgresql.named_types.ENUM"),
+    ("py:class", "_orm.Mapper"),
+    ("py:class", "_orm.registry"),
+    ("py:class", "_schema.MetaData"),
+    ("py:class", "_schema.Table"),
+    ("py:class", "_RegistryType"),
+    ("py:class", "abc.Collection"),
+    ("py:class", "TypeEngine"),
+    ("py:class", "ExternalType"),
+    ("py:class", "UserDefinedType"),
+    ("py:class", "_types.TypeDecorator"),
+    ("py:meth", "_types.TypeDecorator.process_bind_param"),
+    ("py:meth", "_types.TypeDecorator.process_result_value"),
+    ("py:meth", "type_engine"),
     # type vars and aliases / intentionally undocumented
     ("py:class", "RouteHandlerType"),
     ("py:obj", "litestar.security.base.AuthType"),
     ("py:class", "ControllerRouterHandler"),
     ("py:class", "PathParameterDefinition"),
     ("py:class", "BaseSessionBackendT"),
+    ("py:class", "litestar.contrib.repository.abc.CollectionT"),
+    ("py:obj", "ModelT"),
+    ("py:obj", "litestar.contrib.sqlalchemy.repository.ModelT"),
+    ("py:class", "litestar.contrib.sqlalchemy.repository.ModelT"),
+    ("py:class", "ModelT"),
+    ("py:class", "litestar.contrib.sqlalchemy.repository.SelectT"),
     ("py:class", "AnyIOBackend"),
     ("py:class", "T"),
     ("py:class", "C"),

docs/examples/contrib/sqlalchemy/sqlalchemy_async_repository.py

@@ -0,0 +1,204 @@
+from datetime import date
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from pydantic import BaseModel as _BaseModel
+from pydantic import parse_obj_as
+from sqlalchemy import ForeignKey, select
+from sqlalchemy.orm import Mapped, mapped_column, relationship, selectinload
+
+from litestar import Litestar, get
+from litestar.contrib.repository.filters import LimitOffset
+from litestar.contrib.sqlalchemy.base import AuditBase, Base
+from litestar.contrib.sqlalchemy.init_plugin import SQLAlchemyAsyncConfig, SQLAlchemyInitPlugin
+from litestar.contrib.sqlalchemy.repository import SQLAlchemyAsyncRepository
+from litestar.controller import Controller
+from litestar.di import Provide
+from litestar.handlers.http_handlers.decorators import delete, patch, post
+from litestar.pagination import OffsetPagination
+from litestar.params import Parameter
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+
+class BaseModel(_BaseModel):
+    """Extend Pydantic's BaseModel to enable ORM mode"""
+
+    class Config:
+        orm_mode = True
+
+
+# the SQLAlchemy base includes a declarative model for you to use in your models.
+# The `Base` class includes a `UUID` based primary key (`id`)
+class AuthorModel(Base):
+    # we can optionally provide the table name instead of auto-generating it
+    __tablename__ = "author"
+    name: Mapped[str]
+    dob: Mapped[date | None]
+    books: Mapped[list["BookModel"]] = relationship(back_populates="author", lazy="noload")
+
+
+# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2 additional columns: `created` and `updated`.
+# `created` is a timestamp of when the record created, and `updated` is the last time the record was modified.
+class BookModel(AuditBase):
+    __tablename__ = "book"
+    title: Mapped[str]
+    author_id: Mapped[UUID] = mapped_column(ForeignKey("author.id"))
+    author: Mapped["AuthorModel"] = relationship(lazy="joined", innerjoin=True, viewonly=True)
+
+
+# we will explicitly define the schema instead of using DTO objects for clarity.
+
+
+class Author(BaseModel):
+    id: UUID | None
+    name: str
+    dob: date | None = None
+
+
+class AuthorCreate(BaseModel):
+    name: str
+    dob: date | None = None
+
+
+class AuthorUpdate(BaseModel):
+    name: str | None = None
+    dob: date | None = None
+
+
+class AuthorRepository(SQLAlchemyAsyncRepository[AuthorModel]):
+    """Author repository."""
+
+    model_type = AuthorModel
+
+
+async def provide_authors_repo(db_session: "AsyncSession") -> AuthorRepository:
+    """This provides the default Authors repository."""
+    return AuthorRepository(session=db_session)
+
+
+# we can optionally override the default `select` used for the repository to pass in specific SQL options such as join details
+async def provide_author_details_repo(db_session: "AsyncSession") -> AuthorRepository:
+    """This provides a simple example demonstrating how to override the join options for the repository."""
+    return AuthorRepository(statement=select(AuthorModel).options(selectinload(AuthorModel.books)), session=db_session)
+
+
+def provide_limit_offset_pagination(
+    current_page: int = Parameter(ge=1, query="currentPage", default=1, required=False),
+    page_size: int = Parameter(
+        query="pageSize",
+        ge=1,
+        default=10,
+        required=False,
+    ),
+) -> LimitOffset:
+    """Add offset/limit pagination.
+
+    Return type consumed by `Repository.apply_limit_offset_pagination()`.
+
+    Parameters
+    ----------
+    current_page : int
+        LIMIT to apply to select.
+    page_size : int
+        OFFSET to apply to select.
+    """
+    return LimitOffset(page_size, page_size * (current_page - 1))
+
+
+class AuthorController(Controller):
+    """Author CRUD"""
+
+    dependencies = {"authors_repo": Provide(provide_authors_repo)}
+
+    @get(path="/authors")
+    async def list_authors(
+        self,
+        authors_repo: AuthorRepository,
+        limit_offset: LimitOffset,
+    ) -> OffsetPagination[Author]:
+        """List authors."""
+        results, total = await authors_repo.list_and_count(limit_offset)
+        return OffsetPagination[Author](
+            items=parse_obj_as(list[Author], results),
+            total=total,
+            limit=limit_offset.limit,
+            offset=limit_offset.offset,
+        )
+
+    @post(path="/authors")
+    async def create_author(
+        self,
+        authors_repo: AuthorRepository,
+        data: AuthorCreate,
+    ) -> Author:
+        """Create a new author."""
+        obj = await authors_repo.add(AuthorModel(**data.dict(exclude_unset=True, by_alias=False, exclude_none=True)))
+        await authors_repo.session.commit()
+        return Author.from_orm(obj)
+
+    # we override the authors_repo to use the version that joins the Books in
+    @get(path="/authors/{author_id:uuid}", dependencies={"authors_repo": Provide(provide_author_details_repo)})
+    async def get_author(
+        self,
+        authors_repo: AuthorRepository,
+        author_id: UUID = Parameter(
+            title="Author ID",
+            description="The author to retrieve.",
+        ),
+    ) -> Author:
+        """Get an existing author."""
+        obj = await authors_repo.get(author_id)
+        return Author.from_orm(obj)
+
+    @patch(path="/authors/{author_id:uuid}", dependencies={"authors_repo": Provide(provide_author_details_repo)})
+    async def update_author(
+        self,
+        authors_repo: AuthorRepository,
+        data: AuthorUpdate,
+        author_id: UUID = Parameter(
+            title="Author ID",
+            description="The author to update.",
+        ),
+    ) -> Author:
+        """Update an author."""
+        raw_obj = data.dict(exclude_unset=True, by_alias=False, exclude_none=True)
+        raw_obj.update({"id": author_id})
+        obj = await authors_repo.update(AuthorModel(**raw_obj))
+        await authors_repo.session.commit()
+        return Author.from_orm(obj)
+
+    @delete(path="/authors/{author_id:uuid}")
+    async def delete_author(
+        self,
+        authors_repo: AuthorRepository,
+        author_id: UUID = Parameter(
+            title="Author ID",
+            description="The author to delete.",
+        ),
+    ) -> None:
+        """Delete a author from the system."""
+        _ = await authors_repo.delete(author_id)
+        await authors_repo.session.commit()
+
+
+sqlalchemy_config = SQLAlchemyAsyncConfig(
+    connection_string="sqlite+aiosqlite:///test.sqlite", session_dependency_key="db_session"
+)  # Create 'db_session' dependency.
+sqlalchemy_plugin = SQLAlchemyInitPlugin(config=sqlalchemy_config)
+
+
+async def on_startup() -> None:
+    """Initializes the database."""
+    async with sqlalchemy_config.create_engine().begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+app = Litestar(
+    route_handlers=[AuthorController],
+    on_startup=[on_startup],
+    plugins=[SQLAlchemyInitPlugin(config=sqlalchemy_config)],
+    dependencies={"limit_offset": Provide(provide_limit_offset_pagination)},
+    debug=True,
+)

docs/examples/contrib/sqlalchemy/sqlalchemy_declarative_models.py

@@ -0,0 +1,54 @@
+from datetime import date
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from sqlalchemy import ForeignKey, select
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from litestar import Litestar, get
+from litestar.contrib.sqlalchemy.base import AuditBase, Base
+from litestar.contrib.sqlalchemy.init_plugin import SQLAlchemyAsyncConfig, SQLAlchemyInitPlugin
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+
+
+# the SQLAlchemy base includes a declarative model for you to use in your models.
+# The `Base` class includes a `UUID` based primary key (`id`)
+class Author(Base):
+    name: Mapped[str]
+    dob: Mapped[date]
+    books: Mapped[list["Book"]] = relationship(back_populates="author", lazy="selectin")
+
+
+# The `AuditBase` class includes the same UUID` based primary key (`id`) and 2 additional columns: `created` and `updated`.
+# `created` is a timestamp of when the record created, and `updated` is the last time the record was modified.
+class Book(AuditBase):
+    title: Mapped[str]
+    author_id: Mapped[UUID] = mapped_column(ForeignKey("author.id"))
+    author: Mapped[Author] = relationship(lazy="joined", innerjoin=True, viewonly=True)
+
+
+@get(path="/sqlalchemy-app")
+async def async_sqlalchemy_init(db_session: "AsyncSession", db_engine: "AsyncEngine") -> list[Author]:
+    """Interact with SQLAlchemy engine and session."""
+    return await db_session.scalars(select(Author))
+
+
+sqlalchemy_config = SQLAlchemyAsyncConfig(
+    connection_string="sqlite+aiosqlite:///test.sqlite", session_dependency_key="db_session"
+)  # Create 'async_session' dependency.
+sqlalchemy_plugin = SQLAlchemyInitPlugin(config=sqlalchemy_config)
+
+
+async def on_startup() -> None:
+    """Initializes the database."""
+    async with sqlalchemy_config.create_engine().begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+app = Litestar(
+    route_handlers=[async_sqlalchemy_init],
+    on_startup=[on_startup],
+    plugins=[SQLAlchemyInitPlugin(config=sqlalchemy_config)],
+)