feat(litestar): server side session backend (#429)

Implements a server side session backend using SQLAlchemy. Works with an Async or Sync configuration.

Author: cofin

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 .pytest_cache/
 cover/
 test.sqlite
+*.db
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -31,10 +31,11 @@ repos:
       # Run the formatter.
       - id: ruff-format
         types_or: [python, pyi]
-  - repo: https://github.com/crate-ci/typos
-    rev: "v1"
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
     hooks:
-      - id: typos
+      - id: codespell
+        additional_dependencies: [tomli]
   - repo: https://github.com/sphinx-contrib/sphinx-lint
     rev: "v1.0.0"
     hooks:

Makefile

@@ -119,15 +119,14 @@ clean:                                              ## Cleanup temporary build a
 .PHONY: test
 test:                                              ## Run the tests
 	@echo "${INFO} Running test cases... 🧪"
-	@uv run pytest -n 2 --quiet
+	@uv run pytest --dist "loadgroup" -m "" tests -n 2 --quiet
 	@echo "${OK} Tests passed ✨"
 
 .PHONY: coverage
 coverage:                                          ## Run tests with coverage report
 	@echo "${INFO} Running tests with coverage... 📊"
-	@uv run pytest --cov -n auto --quiet
+	@uv run pytest tests --dist "loadgroup" -m "" --cov=advanced_alchemy --cov-report=xml -n 2 --quiet
 	@uv run coverage html >/dev/null 2>&1
-	@uv run coverage xml >/dev/null 2>&1
 	@echo "${OK} Coverage report generated ✨"
 
 # -----------------------------------------------------------------------------

advanced_alchemy/alembic/utils.py

@@ -2,7 +2,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Union
 
-from sqlalchemy import Engine, MetaData, Table
+from sqlalchemy import Column, Engine, MetaData, String, Table
 from typing_extensions import TypeIs
 
 from advanced_alchemy.exceptions import MissingDependencyError
@@ -42,7 +42,15 @@ def _drop_tables_sync(engine: Engine) -> None:
             console.rule("[bold red]Dropping the db", align="left")
             metadata.drop_all(db)
             console.rule("[bold red]Dropping the version table", align="left")
-            Table(version_table_name, metadata).drop(db, checkfirst=True)
+            # Create a properly defined Alembic version table with required column structure
+            # Using a temporary metadata instance prevents modifying the shared metadata object
+            temp_metadata = MetaData()
+            alembic_version_table = Table(
+                version_table_name,
+                temp_metadata,
+                Column("version_num", String(32), primary_key=True, nullable=False),
+            )
+            alembic_version_table.drop(db, checkfirst=True)
         console.rule("[bold yellow]Successfully dropped all objects", align="left")
 
     async def _drop_tables_async(engine: "AsyncEngine") -> None:
@@ -51,7 +59,15 @@ async def _drop_tables_async(engine: "AsyncEngine") -> None:
             console.rule("[bold red]Dropping the db", align="left")
             await db.run_sync(metadata.drop_all)
             console.rule("[bold red]Dropping the version table", align="left")
-            await db.run_sync(Table(version_table_name, metadata).drop, checkfirst=True)
+            # Create a properly defined Alembic version table with required column structure
+            # Using a temporary metadata instance prevents modifying the shared metadata object
+            temp_metadata = MetaData()
+            alembic_version_table = Table(
+                version_table_name,
+                temp_metadata,
+                Column("version_num", String(32), primary_key=True, nullable=False),
+            )
+            await db.run_sync(alembic_version_table.drop, checkfirst=True)
         console.rule("[bold yellow]Successfully dropped all objects", align="left")
 
     if _is_sync(engine):

advanced_alchemy/extensions/litestar/__init__.py

@@ -1,7 +1,7 @@
 from advanced_alchemy import base, exceptions, filters, mixins, operations, repository, service, types, utils
 from advanced_alchemy.alembic.commands import AlembicCommands
 from advanced_alchemy.config import AlembicAsyncConfig, AlembicSyncConfig, AsyncSessionConfig, SyncSessionConfig
-from advanced_alchemy.extensions.litestar import providers
+from advanced_alchemy.extensions.litestar import providers, session, store
 from advanced_alchemy.extensions.litestar.cli import get_database_migration_plugin
 from advanced_alchemy.extensions.litestar.dto import SQLAlchemyDTO, SQLAlchemyDTOConfig
 from advanced_alchemy.extensions.litestar.plugins import (
@@ -64,6 +64,8 @@
     "providers",
     "repository",
     "service",
+    "session",
+    "store",
     "sync_autocommit_before_send_handler",
     "sync_autocommit_handler_maker",
     "sync_default_before_send_handler",

advanced_alchemy/extensions/litestar/plugins/__init__.py

@@ -41,6 +41,9 @@ def on_app_init(self, app_config: AppConfig) -> AppConfig:
 
         Args:
             app_config: The :class:`AppConfig <.config.app.AppConfig>` instance.
+
+        Returns:
+            The :class:`AppConfig <.config.app.AppConfig>` instance.
         """
         app_config.plugins.extend([SQLAlchemyInitPlugin(config=self._config), SQLAlchemySerializationPlugin()])
         return app_config