feat!: refactor Litestar extension - remove wrapper classes, unify handlers (#96)

## Summary

Major refactor of the Litestar extension that removes the `DatabaseConfig` wrapper class pattern, unifies duplicate handler files, and fixes type errors and test pollution issues.

## Breaking Changes

**BREAKING**: The `DatabaseConfig` wrapper class has been removed. 

### Before
```python
from sqlspec.extensions.litestar import DatabaseConfig, SQLSpecPlugin
from sqlspec.adapters.asyncpg import AsyncpgConfig

asyncpg_config = AsyncpgConfig(pool_config={"dsn": "..."})
db_config = DatabaseConfig(config=asyncpg_config)  # Wrapper!
plugin = SQLSpecPlugin(configs=[db_config])
```

### After
```python
from sqlspec import SQLSpec
from sqlspec.extensions.litestar import SQLSpecPlugin
from sqlspec.adapters.asyncpg import AsyncpgConfig

asyncpg_config = AsyncpgConfig(
    pool_config={"dsn": "..."},
    extension_config={"litestar": {"commit_mode": "autocommit"}}
)
sql = SQLSpec()
sql.add_config(asyncpg_config)
plugin = SQLSpecPlugin(sqlspec=sql)
```

## Migration Guide

1. **Remove `DatabaseConfig` wrapper**:
   - Pass core config classes directly to `SQLSpec`
   - Use `extension_config` field for Litestar-specific settings

2. **Update Litestar plugin initialization**:
   - Create `SQLSpec()` instance
   - Add configs with `sql.add_config()`
   - Pass `SQLSpec` instance to `SQLSpecPlugin(sqlspec=sql)`

3. **Move Litestar settings to `extension_config`**:
   ```python
   config = AsyncpgConfig(
       pool_config={"dsn": "..."},
       extension_config={
           "litestar": {
               "connection_key": "db_connection",
               "pool_key": "db_pool", 
               "session_key": "db_session",
               "commit_mode": "autocommit"
           }
       }
   )
   ```

## Changes

### Removed DatabaseConfig Wrapper Class
- **Deleted**: `sqlspec/extensions/litestar/config.py` (292 lines)
- **Deleted**: `tests/unit/test_extensions/test_litestar/test_config.py` (482 lines)
- Plugin now accepts `SQLSpec` instance directly
- All configs from `SQLSpec` are automatically included

### Added extension_config Infrastructure
- Added `extension_config` field to all core database config classes
- Added `LitestarConfig` TypedDict for type-safe Litestar configuration
- Configs read from `extension_config["litestar"]` namespace

### Unified Handler Implementation
- **Merged**: `handlers_async.py` + `handlers_sync.py` → `handlers.py`
- Single implementation with conditional `is_async` logic
- Direct `await` for async drivers, `ensure_async_()` for sync drivers
- Simplified plugin with single `_setup_handlers()` method

### Plugin Refactoring
- Rewritten to work directly with core configs
- Uses `config.is_async` to route to appropriate handlers
- Eliminated wrapper overhead and complexity
- Cleaner dependency injection setup

### Fixed Type Errors
- Removed dead `pool_type` code
- Fixed `"Never" is not awaitable` errors
- Removed redundant `get_config()` delegation
- All mypy and pyright errors resolved

### Fixed Test Database File Pollution
- Tests no longer create 30+ database files in project root
- Fixed SQLite URI mode handling (7 locations)
- Converted hardcoded paths to use pytest `tmp_path` (5 locations)
- Added defensive validation to SQLite config classes

### Code Quality Improvements
- Removed defensive programming anti-patterns
- Fixed nested import violations
- Enforced CLAUDE.md standards throughout
- All functions under 75-line limit

## Benefits

- **Simpler API**: No wrapper classes, direct config usage
- **Less Code**: Removed ~774 lines (wrapper + duplicate handlers)
- **Type Safety**: mypy and pyright clean
- **Better Architecture**: Plugin uses core configs directly
- **Cleaner Tests**: No file pollution, proper temp directories

## Test Results

```
✅ 14/14 Litestar handler tests passing
✅ 230/230 integration tests passing  
✅ mypy: 0 errors
✅ pyright: 0 errors
✅ ruff: all checks passed
```

## Files Changed

```
24 files changed, 808 insertions(+), 1118 deletions(-)
```

**Major changes**:
- Deleted wrapper class and duplicate handlers
- Refactored plugin to use `SQLSpec` directly
- Added `extension_config` infrastructure
- Fixed all type errors and test pollution
- Updated all examples and documentation

## Related

- Supersedes portions of PR #83
- Includes merged PR #97 (handler unification + fixes)

Author: cofin

.gitignore

@@ -62,5 +62,5 @@ benchmarks/
 .crush
 CRUSH.md
 *.md
-!README.md
-!CONTRIBUTING.md
+!./README.md
+!./CONTRIBUTING.md

Makefile

@@ -43,15 +43,15 @@ install-uv:                                         ## Install latest version of
 .PHONY: install
 install: destroy clean                              ## Install the project, dependencies, and pre-commit
 	@echo "${INFO} Starting fresh installation..."
-	@uv python pin 3.12 >/dev/null 2>&1
+	@uv python pin 3.10 >/dev/null 2>&1
 	@uv venv >/dev/null 2>&1
 	@uv sync --all-extras --dev
 	@echo "${OK} Installation complete! 🎉"
 
 .PHONY: install-compiled
 install-compiled: destroy clean                  ## Install with mypyc compilation for performance
 	@echo "${INFO} Starting fresh installation with mypyc compilation..."
-	@uv python pin 3.12 >/dev/null 2>&1
+	@uv python pin 3.10 >/dev/null 2>&1
 	@uv venv >/dev/null 2>&1
 	@echo "${INFO} Installing in editable mode with mypyc compilation..."
 	@HATCH_BUILD_HOOKS_ENABLE=1 uv pip install -e .

docs/examples/litestar_asyncpg.py

@@ -24,9 +24,10 @@
 
 from litestar import Litestar, get
 
-from sqlspec import SQL
+from sqlspec import SQLSpec
 from sqlspec.adapters.asyncpg import AsyncpgConfig, AsyncpgDriver, AsyncpgPoolConfig
-from sqlspec.extensions.litestar import DatabaseConfig, SQLSpec
+from sqlspec.core.statement import SQL
+from sqlspec.extensions.litestar import SQLSpecPlugin
 
 
 @get("/")
@@ -70,19 +71,17 @@ async def get_status() -> dict[str, str]:
 
 # Configure SQLSpec with AsyncPG
 # Note: Modify this DSN to match your database configuration
-sqlspec = SQLSpec(
-    config=[
-        DatabaseConfig(
-            config=AsyncpgConfig(
-                pool_config=AsyncpgPoolConfig(
-                    dsn="postgresql://postgres:postgres@localhost:5433/postgres", min_size=5, max_size=5
-                )
-            ),
-            commit_mode="autocommit",
-        )
-    ]
+sql = SQLSpec()
+sql.add_config(
+    AsyncpgConfig(
+        pool_config=AsyncpgPoolConfig(
+            dsn="postgresql://postgres:postgres@localhost:5433/postgres", min_size=5, max_size=5
+        ),
+        extension_config={"litestar": {"commit_mode": "autocommit"}},
+    )
 )
-app = Litestar(route_handlers=[hello_world, get_version, list_tables, get_status], plugins=[sqlspec], debug=True)
+plugin = SQLSpecPlugin(sqlspec=sql)
+app = Litestar(route_handlers=[hello_world, get_version, list_tables, get_status], plugins=[plugin], debug=True)
 
 if __name__ == "__main__":
     import os

docs/examples/litestar_duckllm.py

@@ -16,8 +16,9 @@
 from litestar import Litestar, post
 from msgspec import Struct
 
+from sqlspec import SQLSpec
 from sqlspec.adapters.duckdb import DuckDBConfig, DuckDBDriver
-from sqlspec.extensions.litestar import SQLSpec
+from sqlspec.extensions.litestar import SQLSpecPlugin
 
 
 class ChatMessage(Struct):
@@ -30,8 +31,9 @@ def duckllm_chat(db_session: DuckDBDriver, data: ChatMessage) -> ChatMessage:
     return db_session.to_schema(results or {"message": "No response from DuckLLM"}, schema_type=ChatMessage)
 
 
-sqlspec = SQLSpec(
-    config=DuckDBConfig(
+sql = SQLSpec()
+sql.add_config(
+    DuckDBConfig(
         driver_features={
             "extensions": [{"name": "open_prompt"}],
             "secrets": [
@@ -48,7 +50,8 @@ def duckllm_chat(db_session: DuckDBDriver, data: ChatMessage) -> ChatMessage:
         }
     )
 )
-app = Litestar(route_handlers=[duckllm_chat], plugins=[sqlspec], debug=True)
+plugin = SQLSpecPlugin(sqlspec=sql)
+app = Litestar(route_handlers=[duckllm_chat], plugins=[plugin], debug=True)
 
 if __name__ == "__main__":
     import uvicorn

docs/examples/litestar_multi_db.py

@@ -15,10 +15,11 @@
 
 from litestar import Litestar, get
 
+from sqlspec import SQLSpec
 from sqlspec.adapters.aiosqlite import AiosqliteConfig, AiosqliteDriver
 from sqlspec.adapters.duckdb import DuckDBConfig, DuckDBDriver
 from sqlspec.core.statement import SQL
-from sqlspec.extensions.litestar import DatabaseConfig, SQLSpec
+from sqlspec.extensions.litestar import SQLSpecPlugin
 
 
 @get("/test", sync_to_thread=True)
@@ -35,22 +36,19 @@ async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
     return {"greeting": greeting["greeting"] if greeting is not None else "hi"}
 
 
-sqlspec = SQLSpec(
-    config=[
-        DatabaseConfig(config=AiosqliteConfig(), commit_mode="autocommit"),
-        DatabaseConfig(
-            config=DuckDBConfig(
-                driver_features={
-                    "extensions": [{"name": "vss", "force_install": True}],
-                    "secrets": [{"secret_type": "s3", "name": "s3_secret", "value": {"key_id": "abcd"}}],
-                }
-            ),
-            connection_key="etl_connection",
-            session_key="etl_session",
-        ),
-    ]
+sql = SQLSpec()
+sql.add_config(AiosqliteConfig(extension_config={"litestar": {"commit_mode": "autocommit"}}))
+sql.add_config(
+    DuckDBConfig(
+        driver_features={
+            "extensions": [{"name": "vss", "force_install": True}],
+            "secrets": [{"secret_type": "s3", "name": "s3_secret", "value": {"key_id": "abcd"}}],
+        },
+        extension_config={"litestar": {"connection_key": "etl_connection", "session_key": "etl_session"}},
+    )
 )
-app = Litestar(route_handlers=[simple_sqlite, simple_select], plugins=[sqlspec])
+plugin = SQLSpecPlugin(sqlspec=sql)
+app = Litestar(route_handlers=[simple_sqlite, simple_select], plugins=[plugin])
 
 if __name__ == "__main__":
     import os

docs/examples/litestar_psycopg.py

@@ -15,29 +15,27 @@
 
 from litestar import Litestar, get
 
+from sqlspec import SQLSpec
 from sqlspec.adapters.psycopg import PsycopgAsyncConfig, PsycopgAsyncDriver
-from sqlspec.extensions.litestar import DatabaseConfig, SQLSpec
+from sqlspec.core.statement import SQL
+from sqlspec.extensions.litestar import SQLSpecPlugin
 
 
 @get("/")
 async def simple_psycopg(db_session: PsycopgAsyncDriver) -> dict[str, str]:
-    from sqlspec.core.statement import SQL
-
     result = await db_session.execute(SQL("SELECT 'Hello, world!' AS greeting"))
     return result.get_first() or {"greeting": "No result found"}
 
 
-sqlspec = SQLSpec(
-    config=[
-        DatabaseConfig(
-            config=PsycopgAsyncConfig(
-                pool_config={"conninfo": "postgres://app:app@localhost:15432/app", "min_size": 1, "max_size": 3}
-            ),
-            commit_mode="autocommit",
-        )
-    ]
+sql = SQLSpec()
+sql.add_config(
+    PsycopgAsyncConfig(
+        pool_config={"conninfo": "postgres://app:app@localhost:15432/app", "min_size": 1, "max_size": 3},
+        extension_config={"litestar": {"commit_mode": "autocommit"}},
+    )
 )
-app = Litestar(route_handlers=[simple_psycopg], plugins=[sqlspec])
+plugin = SQLSpecPlugin(sqlspec=sql)
+app = Litestar(route_handlers=[simple_psycopg], plugins=[plugin])
 
 if __name__ == "__main__":
     import os

docs/examples/litestar_single_db.py

@@ -8,8 +8,9 @@
 from aiosqlite import Connection
 from litestar import Litestar, get
 
+from sqlspec import SQLSpec
 from sqlspec.adapters.aiosqlite import AiosqliteConfig
-from sqlspec.extensions.litestar import SQLSpec
+from sqlspec.extensions.litestar import SQLSpecPlugin
 
 
 @get("/")
@@ -23,5 +24,7 @@ async def simple_sqlite(db_connection: Connection) -> dict[str, str]:
     return {"greeting": next(iter(result))[0]}
 
 
-sqlspec = SQLSpec(config=AiosqliteConfig())
-app = Litestar(route_handlers=[simple_sqlite], plugins=[sqlspec])
+sql = SQLSpec()
+sql.add_config(AiosqliteConfig())
+plugin = SQLSpecPlugin(sqlspec=sql)
+app = Litestar(route_handlers=[simple_sqlite], plugins=[plugin])

sqlspec/adapters/aiosqlite/config.py

@@ -79,6 +79,15 @@ def __init__(
         if "database" not in config_dict or config_dict["database"] == ":memory:":
             config_dict["database"] = "file::memory:?cache=shared"
             config_dict["uri"] = True
+        elif "database" in config_dict:
+            database_path = str(config_dict["database"])
+            if database_path.startswith("file:") and not config_dict.get("uri"):
+                logger.debug(
+                    "Database URI detected (%s) but uri=True not set. "
+                    "Auto-enabling URI mode to prevent physical file creation.",
+                    database_path,
+                )
+                config_dict["uri"] = True
 
         super().__init__(
             pool_config=config_dict,

sqlspec/adapters/sqlite/config.py

@@ -1,5 +1,6 @@
 """SQLite database configuration with thread-local connections."""
 
+import logging
 import uuid
 from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
@@ -11,6 +12,8 @@
 from sqlspec.adapters.sqlite.pool import SqliteConnectionPool
 from sqlspec.config import SyncDatabaseConfig
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from collections.abc import Generator
 
@@ -64,6 +67,15 @@ def __init__(
         if "database" not in pool_config or pool_config["database"] == ":memory:":
             pool_config["database"] = f"file:memory_{uuid.uuid4().hex}?mode=memory&cache=private"
             pool_config["uri"] = True
+        elif "database" in pool_config:
+            database_path = str(pool_config["database"])
+            if database_path.startswith("file:") and not pool_config.get("uri"):
+                logger.debug(
+                    "Database URI detected (%s) but uri=True not set. "
+                    "Auto-enabling URI mode to prevent physical file creation.",
+                    database_path,
+                )
+                pool_config["uri"] = True
 
         super().__init__(
             bind_key=bind_key,

sqlspec/base.py

@@ -161,6 +161,15 @@ def get_config(
         logger.debug("Retrieved configuration: %s", self._get_config_name(name))
         return config
 
+    @property
+    def configs(self) -> "dict[type, DatabaseConfigProtocol[Any, Any, Any]]":
+        """Access the registry of database configurations.
+
+        Returns:
+            Dictionary mapping config types to config instances.
+        """
+        return self._configs
+
     @overload
     def get_connection(
         self,