sqlspec 0.20.0__py3-none-any.whl → 0.21.0__py3-none-any.whl

sqlspec/extensions/litestar/config.py

@@ -1,7 +1,8 @@
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Literal, Optional, Union, cast
 
 from sqlspec.exceptions import ImproperConfigurationError
+from sqlspec.extensions.litestar._utils import get_sqlspec_scope_state, set_sqlspec_scope_state
 from sqlspec.extensions.litestar.handlers import (
     autocommit_handler_maker,
     connection_provider_maker,
@@ -13,13 +14,14 @@ from sqlspec.extensions.litestar.handlers import (
 
 if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Awaitable
-    from contextlib import AbstractAsyncContextManager
+    from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
     from litestar import Litestar
     from litestar.datastructures.state import State
     from litestar.types import BeforeMessageSendHookHandler, Scope
 
     from sqlspec.config import AsyncConfigT, DriverT, SyncConfigT
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
     from sqlspec.typing import ConnectionT, PoolT
 
 
@@ -34,8 +36,10 @@ __all__ = (
     "DEFAULT_CONNECTION_KEY",
     "DEFAULT_POOL_KEY",
     "DEFAULT_SESSION_KEY",
+    "AsyncDatabaseConfig",
     "CommitMode",
     "DatabaseConfig",
+    "SyncDatabaseConfig",
 )
 
 
@@ -90,3 +94,183 @@ class DatabaseConfig:
         self.session_provider = session_provider_maker(
             config=self.config, connection_dependency_key=self.connection_key
         )
+
+    def get_request_session(
+        self, state: "State", scope: "Scope"
+    ) -> "Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]":
+        """Get a session instance from the current request.
+
+        This method provides access to the database session that has been added to the request
+        scope, similar to Advanced Alchemy's provide_session method. It first looks for an
+        existing session in the request scope state, and if not found, creates a new one using
+        the connection from the scope.
+
+        Args:
+            state: The Litestar application State object.
+            scope: The ASGI scope containing the request context.
+
+        Returns:
+            A driver session instance.
+
+        Raises:
+            ImproperConfigurationError: If no connection is available in the scope.
+        """
+        # Create a unique scope key for sessions to avoid conflicts
+        session_scope_key = f"{self.session_key}_instance"
+
+        # Try to get existing session from scope
+        session = get_sqlspec_scope_state(scope, session_scope_key)
+        if session is not None:
+            return cast("Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]", session)
+
+        # Get connection from scope state
+        connection = get_sqlspec_scope_state(scope, self.connection_key)
+        if connection is None:
+            msg = f"No database connection found in scope for key '{self.connection_key}'. "
+            msg += "Ensure the connection dependency is properly configured and available."
+            raise ImproperConfigurationError(detail=msg)
+
+        # Create new session using the connection
+        # Access driver_type which is available on all config types
+        session = self.config.driver_type(connection=connection)  # type: ignore[union-attr]
+
+        # Store session in scope for future use
+        set_sqlspec_scope_state(scope, session_scope_key, session)
+
+        return cast("Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]", session)
+
+    def get_request_connection(self, state: "State", scope: "Scope") -> "Any":
+        """Get a connection instance from the current request.
+
+        This method provides access to the database connection that has been added to the request
+        scope. This is useful in guards, middleware, or other contexts where you need direct
+        access to the connection that's been established for the current request.
+
+        Args:
+            state: The Litestar application State object.
+            scope: The ASGI scope containing the request context.
+
+        Returns:
+            A database connection instance.
+
+        Raises:
+            ImproperConfigurationError: If no connection is available in the scope.
+        """
+        connection = get_sqlspec_scope_state(scope, self.connection_key)
+        if connection is None:
+            msg = f"No database connection found in scope for key '{self.connection_key}'. "
+            msg += "Ensure the connection dependency is properly configured and available."
+            raise ImproperConfigurationError(detail=msg)
+
+        return cast("Any", connection)
+
+
+# Add passthrough methods to both specialized classes for convenience
+class SyncDatabaseConfig(DatabaseConfig):
+    """Sync-specific DatabaseConfig with better typing for get_request_session."""
+
+    def get_request_session(self, state: "State", scope: "Scope") -> "SyncDriverAdapterBase":
+        """Get a sync session instance from the current request.
+
+        This method provides access to the database session that has been added to the request
+        scope, similar to Advanced Alchemy's provide_session method. It first looks for an
+        existing session in the request scope state, and if not found, creates a new one using
+        the connection from the scope.
+
+        Args:
+            state: The Litestar application State object.
+            scope: The ASGI scope containing the request context.
+
+        Returns:
+            A sync driver session instance.
+        """
+        session = super().get_request_session(state, scope)
+        return cast("SyncDriverAdapterBase", session)
+
+    def provide_session(self) -> "AbstractContextManager[SyncDriverAdapterBase]":
+        """Provide a database session context manager.
+
+        This is a passthrough to the underlying config's provide_session method
+        for convenient access to database sessions.
+
+        Returns:
+            Context manager that yields a sync driver session.
+        """
+        return self.config.provide_session()  # type: ignore[union-attr,no-any-return]
+
+    def provide_connection(self) -> "AbstractContextManager[Any]":
+        """Provide a database connection context manager.
+
+        This is a passthrough to the underlying config's provide_connection method
+        for convenient access to database connections.
+
+        Returns:
+            Context manager that yields a sync database connection.
+        """
+        return self.config.provide_connection()  # type: ignore[union-attr,no-any-return]
+
+    def create_connection(self) -> "Any":
+        """Create and return a new database connection.
+
+        This is a passthrough to the underlying config's create_connection method
+        for direct connection creation without context management.
+
+        Returns:
+            A new sync database connection.
+        """
+        return self.config.create_connection()  # type: ignore[union-attr]
+
+
+class AsyncDatabaseConfig(DatabaseConfig):
+    """Async-specific DatabaseConfig with better typing for get_request_session."""
+
+    def get_request_session(self, state: "State", scope: "Scope") -> "AsyncDriverAdapterBase":
+        """Get an async session instance from the current request.
+
+        This method provides access to the database session that has been added to the request
+        scope, similar to Advanced Alchemy's provide_session method. It first looks for an
+        existing session in the request scope state, and if not found, creates a new one using
+        the connection from the scope.
+
+        Args:
+            state: The Litestar application State object.
+            scope: The ASGI scope containing the request context.
+
+        Returns:
+            An async driver session instance.
+        """
+        session = super().get_request_session(state, scope)
+        return cast("AsyncDriverAdapterBase", session)
+
+    def provide_session(self) -> "AbstractAsyncContextManager[AsyncDriverAdapterBase]":
+        """Provide a database session context manager.
+
+        This is a passthrough to the underlying config's provide_session method
+        for convenient access to database sessions.
+
+        Returns:
+            Context manager that yields an async driver session.
+        """
+        return self.config.provide_session()  # type: ignore[union-attr,no-any-return]
+
+    def provide_connection(self) -> "AbstractAsyncContextManager[Any]":
+        """Provide a database connection context manager.
+
+        This is a passthrough to the underlying config's provide_connection method
+        for convenient access to database connections.
+
+        Returns:
+            Context manager that yields an async database connection.
+        """
+        return self.config.provide_connection()  # type: ignore[union-attr,no-any-return]
+
+    async def create_connection(self) -> "Any":
+        """Create and return a new database connection.
+
+        This is a passthrough to the underlying config's create_connection method
+        for direct connection creation without context management.
+
+        Returns:
+            A new async database connection.
+        """
+        return await self.config.create_connection()  # type: ignore[union-attr]

sqlspec/extensions/litestar/plugin.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
 from litestar.di import Provide
 from litestar.plugins import CLIPlugin, InitPluginProtocol
@@ -6,14 +6,17 @@ from litestar.plugins import CLIPlugin, InitPluginProtocol
 from sqlspec.base import SQLSpec as SQLSpecBase
 from sqlspec.config import AsyncConfigT, DatabaseConfigProtocol, DriverT, SyncConfigT
 from sqlspec.exceptions import ImproperConfigurationError
-from sqlspec.extensions.litestar.config import DatabaseConfig
+from sqlspec.extensions.litestar.config import AsyncDatabaseConfig, DatabaseConfig, SyncDatabaseConfig
 from sqlspec.typing import ConnectionT, PoolT
 from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from click import Group
     from litestar.config.app import AppConfig
+    from litestar.datastructures.state import State
+    from litestar.types import Scope
 
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
     from sqlspec.loader import SQLFileLoader
 
 logger = get_logger("extensions.litestar")
@@ -131,11 +134,242 @@ class SQLSpec(SQLSpecBase, InitPluginProtocol, CLIPlugin):
             The annotation for the configuration.
         """
         for c in self.config:
-            if key == c.config or key in {c.annotation, c.connection_key, c.pool_key}:
+            # Check annotation only if it's been set (during on_app_init)
+            annotation_match = hasattr(c, "annotation") and key == c.annotation
+            if key == c.config or annotation_match or key in {c.connection_key, c.pool_key}:
+                if not hasattr(c, "annotation"):
+                    msg = (
+                        "Annotation not set for configuration. Ensure the plugin has been initialized with on_app_init."
+                    )
+                    raise AttributeError(msg)
                 return c.annotation
         msg = f"No configuration found for {key}"
         raise KeyError(msg)
 
+    @overload
+    def get_config(self, name: "type[SyncConfigT]") -> "SyncConfigT": ...
+
+    @overload
+    def get_config(self, name: "type[AsyncConfigT]") -> "AsyncConfigT": ...
+
+    @overload
+    def get_config(self, name: str) -> "DatabaseConfig": ...
+
+    @overload
+    def get_config(self, name: "type[SyncDatabaseConfig]") -> "SyncDatabaseConfig": ...
+
+    @overload
+    def get_config(self, name: "type[AsyncDatabaseConfig]") -> "AsyncDatabaseConfig": ...
+
+    def get_config(
+        self, name: "Union[type[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]], str, Any]"
+    ) -> "Union[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT], DatabaseConfig, SyncDatabaseConfig, AsyncDatabaseConfig]":
+        """Get a configuration instance by name, supporting both base behavior and Litestar extensions.
+
+        This method extends the base get_config to support Litestar-specific lookup patterns
+        while maintaining compatibility with the base class signature. It supports lookup by
+        connection key, pool key, session key, config instance, or annotation type.
+
+        Args:
+            name: The configuration identifier - can be:
+                - Type annotation (base class behavior)
+                - connection_key (e.g., "auth_db_connection")
+                - pool_key (e.g., "analytics_db_pool")
+                - session_key (e.g., "reporting_db_session")
+                - config instance
+                - annotation type
+
+        Raises:
+            KeyError: If no configuration is found for the given name.
+
+        Returns:
+            The configuration instance for the specified name.
+        """
+        # First try base class behavior for type-based lookup
+        # Only call super() if name matches the expected base class types
+        if not isinstance(name, str):
+            try:
+                return super().get_config(name)  # type: ignore[no-any-return]
+            except (KeyError, AttributeError):
+                # Fall back to Litestar-specific lookup patterns
+                pass
+
+        # Litestar-specific lookups by string keys
+        if isinstance(name, str):
+            for c in self.config:
+                if name in {c.connection_key, c.pool_key, c.session_key}:
+                    return c  # Return the DatabaseConfig wrapper for string lookups
+
+        # Lookup by config instance or annotation
+        for c in self.config:
+            annotation_match = hasattr(c, "annotation") and name == c.annotation
+            if name == c.config or annotation_match:
+                return c.config  # Return the underlying config for type-based lookups
+
+        msg = f"No database configuration found for name '{name}'. Available keys: {self._get_available_keys()}"
+        raise KeyError(msg)
+
+    def provide_request_session(
+        self,
+        key: "Union[str, SyncConfigT, AsyncConfigT, type[Union[SyncConfigT, AsyncConfigT]]]",
+        state: "State",
+        scope: "Scope",
+    ) -> "Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]":
+        """Provide a database session for the specified configuration key from request scope.
+
+        This is a convenience method that combines get_config and get_request_session
+        into a single call, similar to Advanced Alchemy's provide_session pattern.
+
+        Args:
+            key: The configuration identifier (same as get_config)
+            state: The Litestar application State object
+            scope: The ASGI scope containing the request context
+
+        Returns:
+            A driver session instance for the specified database configuration
+
+        Example:
+            >>> sqlspec_plugin = connection.app.state.sqlspec
+            >>> # Direct session access by key
+            >>> auth_session = sqlspec_plugin.provide_request_session(
+            ...     "auth_db", state, scope
+            ... )
+            >>> analytics_session = sqlspec_plugin.provide_request_session(
+            ...     "analytics_db", state, scope
+            ... )
+        """
+        # Get DatabaseConfig wrapper for Litestar methods
+        db_config = self._get_database_config(key)
+        return db_config.get_request_session(state, scope)
+
+    def provide_sync_request_session(
+        self, key: "Union[str, SyncConfigT, type[SyncConfigT]]", state: "State", scope: "Scope"
+    ) -> "SyncDriverAdapterBase":
+        """Provide a sync database session for the specified configuration key from request scope.
+
+        This method provides better type hints for sync database sessions, ensuring the returned
+        session is properly typed as SyncDriverAdapterBase for better IDE support and type safety.
+
+        Args:
+            key: The sync configuration identifier
+            state: The Litestar application State object
+            scope: The ASGI scope containing the request context
+
+        Returns:
+            A sync driver session instance for the specified database configuration
+
+        Example:
+            >>> sqlspec_plugin = connection.app.state.sqlspec
+            >>> auth_session = sqlspec_plugin.provide_sync_request_session(
+            ...     "auth_db", state, scope
+            ... )
+            >>> # auth_session is now correctly typed as SyncDriverAdapterBase
+        """
+        # Get DatabaseConfig wrapper for Litestar methods
+        db_config = self._get_database_config(key)
+        session = db_config.get_request_session(state, scope)
+        return cast("SyncDriverAdapterBase", session)
+
+    def provide_async_request_session(
+        self, key: "Union[str, AsyncConfigT, type[AsyncConfigT]]", state: "State", scope: "Scope"
+    ) -> "AsyncDriverAdapterBase":
+        """Provide an async database session for the specified configuration key from request scope.
+
+        This method provides better type hints for async database sessions, ensuring the returned
+        session is properly typed as AsyncDriverAdapterBase for better IDE support and type safety.
+
+        Args:
+            key: The async configuration identifier
+            state: The Litestar application State object
+            scope: The ASGI scope containing the request context
+
+        Returns:
+            An async driver session instance for the specified database configuration
+
+        Example:
+            >>> sqlspec_plugin = connection.app.state.sqlspec
+            >>> auth_session = sqlspec_plugin.provide_async_request_session(
+            ...     "auth_db", state, scope
+            ... )
+            >>> # auth_session is now correctly typed as AsyncDriverAdapterBase
+        """
+        # Get DatabaseConfig wrapper for Litestar methods
+        db_config = self._get_database_config(key)
+        session = db_config.get_request_session(state, scope)
+        return cast("AsyncDriverAdapterBase", session)
+
+    def provide_request_connection(
+        self,
+        key: "Union[str, SyncConfigT, AsyncConfigT, type[Union[SyncConfigT, AsyncConfigT]]]",
+        state: "State",
+        scope: "Scope",
+    ) -> Any:
+        """Provide a database connection for the specified configuration key from request scope.
+
+        This is a convenience method that combines get_config and get_request_connection
+        into a single call.
+
+        Args:
+            key: The configuration identifier (same as get_config)
+            state: The Litestar application State object
+            scope: The ASGI scope containing the request context
+
+        Returns:
+            A database connection instance for the specified database configuration
+
+        Example:
+            >>> sqlspec_plugin = connection.app.state.sqlspec
+            >>> # Direct connection access by key
+            >>> auth_conn = sqlspec_plugin.provide_request_connection(
+            ...     "auth_db", state, scope
+            ... )
+            >>> analytics_conn = sqlspec_plugin.provide_request_connection(
+            ...     "analytics_db", state, scope
+            ... )
+        """
+        # Get DatabaseConfig wrapper for Litestar methods
+        db_config = self._get_database_config(key)
+        return db_config.get_request_connection(state, scope)
+
+    def _get_database_config(
+        self, key: "Union[str, SyncConfigT, AsyncConfigT, type[Union[SyncConfigT, AsyncConfigT]]]"
+    ) -> DatabaseConfig:
+        """Get a DatabaseConfig wrapper instance by name.
+
+        This is used internally by provide_request_session and provide_request_connection
+        to get the DatabaseConfig wrapper that has the request session methods.
+
+        Args:
+            key: The configuration identifier
+
+        Returns:
+            The DatabaseConfig wrapper instance
+
+        Raises:
+            KeyError: If no configuration is found for the given key
+        """
+        # For string keys, lookup by connection/pool/session keys
+        if isinstance(key, str):
+            for c in self.config:
+                if key in {c.connection_key, c.pool_key, c.session_key}:
+                    return c
+
+        # For other keys, lookup by config instance or annotation
+        for c in self.config:
+            annotation_match = hasattr(c, "annotation") and key == c.annotation
+            if key == c.config or annotation_match:
+                return c
+
+        msg = f"No database configuration found for name '{key}'. Available keys: {self._get_available_keys()}"
+        raise KeyError(msg)
+
+    def _get_available_keys(self) -> "list[str]":
+        """Get a list of all available configuration keys for error messages."""
+        keys = []
+        for c in self.config:
+            keys.extend([c.connection_key, c.pool_key, c.session_key])
+        return keys
+
     def _validate_dependency_keys(self) -> None:
         """Validate that connection and pool keys are unique across configurations.
 

{sqlspec-0.20.0.dist-info → sqlspec-0.21.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.20.0
+Version: 0.21.0
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/
@@ -130,16 +130,21 @@ These are just a few examples that demonstrate SQLSpec's flexibility. Each of th
 ```python
 from sqlspec import SQLSpec
 from sqlspec.adapters.sqlite import SqliteConfig
-from pydantic import BaseModel
+
 # Create SQLSpec instance and configure database
-sql = SQLSpec()
-config = sql.add_config(SqliteConfig(database=":memory:"))
+db_manager = SQLSpec()
+config = SqliteConfig(pool_config={"database": ":memory:"}) # Thread local pooling
+db_manager.add_config(config)
 
 # Execute queries with automatic result mapping
-with sql.provide_session(config) as session:
+with db_manager.provide_session(config) as session:
     # Simple query
     result = session.execute("SELECT 'Hello, SQLSpec!' as message")
     print(result.get_first())  # {'message': 'Hello, SQLSpec!'}
+
+    # Type-safe single row query
+    row = session.select_one("SELECT 'Hello, SQLSpec!' as message")
+    print(row)  # {'message': 'Hello, SQLSpec!'}
 ```
 
 ### SQL Builder Example (Experimental)
@@ -150,30 +155,94 @@ with sql.provide_session(config) as session:
 from sqlspec import sql
 
 # Build a simple query
-query = sql.select("id", "name", "email").from_("users").where("active = ?", True)
-print(query.build().sql)  # SELECT id, name, email FROM users WHERE active = ?
+query = sql.select("id", "name", "email").from_("users").where("active = ?")
+statement = query.to_statement()
+print(statement.sql)  # SELECT id, name, email FROM users WHERE active = ?
 
 # More complex example with joins
 query = (
     sql.select("u.name", "COUNT(o.id) as order_count")
     .from_("users u")
     .left_join("orders o", "u.id = o.user_id")
-    .where("u.created_at > ?", "2024-01-01")
+    .where("u.created_at > ?")
     .group_by("u.name")
-    .having("COUNT(o.id) > ?", 5)
+    .having("COUNT(o.id) > ?")
     .order_by("order_count", desc=True)
 )
 
-# Execute the built query
-with sql.provide_session(config) as session:
-    results = session.execute(query.build())
+# Execute the built query with parameters
+with db_manager.provide_session(config) as session:
+    results = session.execute(query, "2024-01-01", 5)
+```
+
+### Type-Safe Result Mapping
+
+SQLSpec supports automatic mapping to typed models using popular libraries:
+
+```python
+from sqlspec import SQLSpec
+from sqlspec.adapters.sqlite import SqliteConfig
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+db_manager = SQLSpec()
+config = SqliteConfig(pool_config={"database": ":memory:"})
+db_manager.add_config(config)
+
+with db_manager.provide_session(config) as session:
+    # Create and populate test data
+    session.execute_script("""
+        CREATE TABLE users (id INTEGER, name TEXT, email TEXT);
+        INSERT INTO users VALUES (1, 'Alice', 'alice@example.com');
+    """)
+    # Map single result to typed model
+    user = session.select_one("SELECT * FROM users WHERE id = ?", 1, schema_type=User)
+    print(f"User: {user.name} ({user.email})")
+
+    # Map multiple results
+    users = session.select("SELECT * FROM users", schema_type=User)
+    for user in users:
+        print(f"User: {user.name}")
+```
+
+### Session Methods Overview
+
+SQLSpec provides several convenient methods for executing queries:
+
+```python
+with db_manager.provide_session(config) as session:
+    # Execute any SQL and get full result set
+    result = session.execute("SELECT * FROM users")
+
+    # Get single row (raises error if not found)
+    user = session.select_one("SELECT * FROM users WHERE id = ?", 1)
+
+    # Get single row or None (no error if not found)
+    maybe_user = session.select_one_or_none("SELECT * FROM users WHERE id = ?", 999)
+
+    # Execute with many parameter sets (bulk operations)
+    session.execute_many(
+        "INSERT INTO users (name, email) VALUES (?, ?)",
+        [("Bob", "bob@example.com"), ("Carol", "carol@example.com")]
+    )
+
+    # Execute multiple statements as a script
+    session.execute_script("""
+        CREATE TABLE IF NOT EXISTS logs (id INTEGER, message TEXT);
+        INSERT INTO logs (message) VALUES ('System started');
+    """)
 ```
 
-### DuckDB LLM
+<details>
+<summary>🦆 DuckDB LLM Integration Example</summary>
 
 This is a quick implementation using some of the built-in Secret and Extension management features of SQLSpec's DuckDB integration.
 
-It allows you to communicate with any compatible OpenAPI conversations endpoint (such as Ollama). This example:
+It allows you to communicate with any compatible OpenAI conversations endpoint (such as Ollama). This example:
 
 - auto installs the `open_prompt` DuckDB extensions
 - automatically creates the correct `open_prompt` compatible secret required to use the extension
@@ -193,11 +262,12 @@ from pydantic import BaseModel
 class ChatMessage(BaseModel):
     message: str
 
-sql = SQLSpec()
-etl_config = sql.add_config(
-    DuckDBConfig(
-        extensions=[{"name": "open_prompt"}],
-        secrets=[
+db_manager = SQLSpec()
+config = DuckDBConfig(
+    pool_config={"database": ":memory:"},
+    driver_features={
+        "extensions": [{"name": "open_prompt"}],
+        "secrets": [
             {
                 "secret_type": "open_prompt",
                 "name": "open_prompt",
@@ -208,9 +278,11 @@ etl_config = sql.add_config(
                 },
             }
         ],
-    )
+    },
 )
-with sql.provide_session(etl_config) as session:
+db_manager.add_config(config)
+
+with db_manager.provide_session(config) as session:
     result = session.select_one(
         "SELECT open_prompt(?)",
         "Can you write a haiku about DuckDB?",
@@ -219,7 +291,10 @@ with sql.provide_session(etl_config) as session:
     print(result) # result is a ChatMessage pydantic model
 ```
 
-### DuckDB Gemini Embeddings
+</details>
+
+<details>
+<summary>🔗 DuckDB Gemini Embeddings Example</summary>
 
 In this example, we are again using DuckDB. However, we are going to use the built-in to call the Google Gemini embeddings service directly from the database.
 
@@ -246,11 +321,12 @@ API_URL = (
     f"https://generativelanguage.googleapis.com/v1beta/models/{EMBEDDING_MODEL}:embedContent?key=${GOOGLE_API_KEY}"
 )
 
-sql = SQLSpec()
-etl_config = sql.add_config(
-    DuckDBConfig(
-        extensions=[{"name": "vss"}, {"name": "http_client"}],
-        on_connection_create=lambda connection: connection.execute(f"""
+db_manager = SQLSpec()
+config = DuckDBConfig(
+    pool_config={"database": ":memory:"},
+    driver_features={
+        "extensions": [{"name": "vss"}, {"name": "http_client"}],
+        "on_connection_create": lambda connection: connection.execute(f"""
             CREATE IF NOT EXISTS MACRO generate_embedding(q) AS (
                 WITH  __request AS (
                     SELECT http_post(
@@ -269,16 +345,77 @@ etl_config = sql.add_config(
                 FROM __request,
             );
         """),
-    )
+    },
 )
-with sql.provide_session(etl_config) as session:
+db_manager.add_config(config)
+
+with db_manager.provide_session(config) as session:
     result = session.execute("SELECT generate_embedding('example text')")
     print(result.get_first()) # result is a dictionary when `schema_type` is omitted.
 ```
 
+</details>
+
+### SQL File Loading
+
+SQLSpec can load and manage SQL queries from files using aiosql-style named queries:
+
+```python
+from sqlspec import SQLSpec
+from sqlspec.loader import SQLFileLoader
+from sqlspec.adapters.sqlite import SqliteConfig
+
+# Initialize with SQL file loader
+db_manager = SQLSpec(loader=SQLFileLoader())
+config = SqliteConfig(pool_config={"database": ":memory:"})
+db_manager.add_config(config)
+
+# Load SQL files from directory
+db_manager.load_sql_files("./sql")
+
+# SQL file: ./sql/users.sql
+# -- name: get_user
+# SELECT * FROM users WHERE id = ?
+#
+# -- name: create_user
+# INSERT INTO users (name, email) VALUES (?, ?)
+
+with db_manager.provide_session(config) as session:
+    # Use named queries from files
+    user = session.execute(db_manager.get_sql("get_user"), 1)
+    session.execute(db_manager.get_sql("create_user"), "Alice", "alice@example.com")
+```
+
+### Database Migrations
+
+SQLSpec includes a built-in migration system for managing schema changes. After configuring your database with migration settings, use the CLI commands:
+
+```bash
+# Initialize migration directory
+sqlspec db init migrations
+
+# Generate new migration file
+sqlspec db make-migrations "Add user table"
+
+# Apply all pending migrations
+sqlspec db upgrade
+
+# Show current migration status
+sqlspec db show-current-revision
+```
+
+For Litestar applications, replace `sqlspec` with your application command:
+
+```bash
+# Using Litestar CLI integration
+litestar db make-migrations "Add user table"
+litestar db upgrade
+litestar db show-current-revision
+```
+
 ### Basic Litestar Integration
 
-In this example we are going to demonstrate how to create a basic configuration that integrates into Litestar.
+In this example we demonstrate how to create a basic configuration that integrates into Litestar:
 
 ```py
 # /// script
@@ -301,7 +438,7 @@ async def simple_sqlite(db_session: AiosqliteDriver) -> dict[str, str]:
 
 sqlspec = SQLSpec(
     config=DatabaseConfig(
-        config=AiosqliteConfig(),
+        config=AiosqliteConfig(pool_config={"database": ":memory:"}), # built in local pooling
         commit_mode="autocommit"
     )
 )
@@ -320,6 +457,41 @@ The primary goal at this stage is to establish a **native connectivity interface
 
 This list is not final. If you have a driver you'd like to see added, please open an issue or submit a PR!
 
+### Configuration Examples
+
+Each adapter uses a consistent configuration pattern with `pool_config` for connection parameters:
+
+```python
+# SQLite
+SqliteConfig(pool_config={"database": "/path/to/database.db"})
+AiosqliteConfig(pool_config={"database": "/path/to/database.db"})  # Async
+AdbcConfig(connection_config={"uri": "sqlite:///path/to/database.db"})  # ADBC
+
+# PostgreSQL (multiple drivers available)
+PsycopgSyncConfig(pool_config={"host": "localhost", "database": "mydb", "user": "user", "password": "pass"})
+PsycopgAsyncConfig(pool_config={"host": "localhost", "database": "mydb", "user": "user", "password": "pass"})  # Async
+AsyncpgConfig(pool_config={"host": "localhost", "database": "mydb", "user": "user", "password": "pass"})
+PsqlpyConfig(pool_config={"dsn": "postgresql://user:pass@localhost/mydb"})
+AdbcConfig(connection_config={"uri": "postgresql://user:pass@localhost/mydb"})  # ADBC
+
+# DuckDB
+DuckDBConfig(pool_config={"database": ":memory:"})  # or file path
+AdbcConfig(connection_config={"uri": "duckdb:///path/to/database.duckdb"})  # ADBC
+
+# MySQL
+AsyncmyConfig(pool_config={"host": "localhost", "database": "mydb", "user": "user", "password": "pass"})  # Async
+
+# Oracle
+OracleSyncConfig(pool_config={"host": "localhost", "service_name": "XEPDB1", "user": "user", "password": "pass"})
+OracleAsyncConfig(pool_config={"host": "localhost", "service_name": "XEPDB1", "user": "user", "password": "pass"})  # Async
+
+# BigQuery
+BigQueryConfig(pool_config={"project": "my-project", "dataset": "my_dataset"})
+AdbcConfig(connection_config={"driver_name": "adbc_driver_bigquery", "project_id": "my-project", "dataset_id": "my_dataset"})  # ADBC
+```
+
+### Supported Drivers
+
 | Driver                                                                                                       | Database   | Mode    | Status     |
 | :----------------------------------------------------------------------------------------------------------- | :--------- | :------ | :--------- |
 | [`adbc`](https://arrow.apache.org/adbc/)                                                                     | Postgres   | Sync    | ✅         |
@@ -342,21 +514,35 @@ This list is not final. If you have a driver you'd like to see added, please ope
 | [`asyncmy`](https://github.com/long2ice/asyncmy)                                                           | MySQL      | Async   | ✅         |
 | [`snowflake`](https://docs.snowflake.com)                                                                    | Snowflake  | Sync    | 🗓️  |
 
-## Proposed Project Structure
+## Project Structure
 
 - `sqlspec/`:
-    - `adapters/`: Contains all database drivers and associated configuration.
-    - `extensions/`:
-        - `litestar/`: Litestar framework integration ✅
-        - `fastapi/`: Future home of `fastapi` integration.
-        - `flask/`: Future home of `flask` integration.
-        - `*/`: Future home of your favorite framework integration
-    - `base.py`: Contains base protocols for database configurations.
-    - `statement/`: Contains the SQL statement system with builders, validation, and transformation.
-    - `storage/`: Contains unified storage operations for data import/export.
-    - `utils/`: Contains utility functions used throughout the project.
-    - `exceptions.py`: Contains custom exceptions for SQLSpec.
-    - `typing.py`: Contains type hints, type guards and several facades for optional libraries that are not required for the core functionality of SQLSpec.
+    - `adapters/`: Database-specific drivers and configuration classes for all supported databases
+    - `extensions/`: Framework integrations and external library adapters
+        - `litestar/`: Litestar web framework integration with dependency injection ✅
+        - `aiosql/`: Integration with aiosql for SQL file loading ✅
+        - Future integrations: `fastapi/`, `flask/`, etc.
+    - `builder/`: Fluent SQL query builder with method chaining and type safety
+        - `mixins/`: Composable query building operations (WHERE, JOIN, ORDER BY, etc.)
+    - `core/`: Core query processing infrastructure
+        - `statement.py`: SQL statement wrapper with metadata and type information
+        - `parameters.py`: Parameter style conversion and validation
+        - `result.py`: Result set handling and type mapping
+        - `compiler.py`: SQL compilation and validation using SQLGlot
+        - `cache.py`: Statement caching for performance optimization
+    - `driver/`: Base driver system with sync/async support and transaction management
+        - `mixins/`: Shared driver capabilities (result processing, SQL translation)
+    - `migrations/`: Database migration system with CLI commands
+    - `storage/`: Unified data import/export operations with multiple backends
+        - `backends/`: Storage backend implementations (fsspec, obstore)
+    - `utils/`: Utility functions, type guards, and helper tools
+    - `base.py`: Main SQLSpec registry and configuration manager
+    - `loader.py`: SQL file loading system for `.sql` files
+    - `cli.py`: Command-line interface for migrations and database operations
+    - `config.py`: Base configuration classes and protocols
+    - `protocols.py`: Type protocols for runtime type checking
+    - `exceptions.py`: Custom exception hierarchy for SQLSpec
+    - `typing.py`: Type definitions, guards, and optional dependency facades
 
 ## Get Involved
 

{sqlspec-0.20.0.dist-info → sqlspec-0.21.0.dist-info}/RECORD

@@ -101,9 +101,9 @@ sqlspec/extensions/aiosql/adapter.py,sha256=WshAQkpNJQ9zCMcL7EuAc6axl90GwRp3oBZ4
 sqlspec/extensions/litestar/__init__.py,sha256=tOmQ7RHSWOot7p30gk0efxxuP0OCq1opyyZqNmQY7FE,320
 sqlspec/extensions/litestar/_utils.py,sha256=iaicqnnkC5CuDwJKStz0T7lFaYMrgR96SYKZpe71v2g,1950
 sqlspec/extensions/litestar/cli.py,sha256=X4DlAx3Ry-ccOjAQSxe8SMtyJKCFJVLTbENPU_efKuU,1356
-sqlspec/extensions/litestar/config.py,sha256=3UI_vhtbupCLsf1nhUgUpRlCoUS5c0GsAjWvegT0c3c,4462
+sqlspec/extensions/litestar/config.py,sha256=AXAQsjc_tb88wk31d4v31e_6oOtDKz9DS0NA7wg_3Q8,12414
 sqlspec/extensions/litestar/handlers.py,sha256=DXYO1FUOmG3YE4E7RlxWCPNl8YgbUzVO8pHgwZeuDOw,10625
-sqlspec/extensions/litestar/plugin.py,sha256=u4Mjq16EYb4oxzbONCLdQY2P40Po-e8wQXnVnJKXGCA,5732
+sqlspec/extensions/litestar/plugin.py,sha256=4G_r3lna1TClWXnYXJwAYAH52z_t9cbrbLBn83Utmpg,15974
 sqlspec/extensions/litestar/providers.py,sha256=5LRb5JvRV_XZdNOKkdaIy3j5x-dFCcAi1ea1pgwuapI,18882
 sqlspec/migrations/__init__.py,sha256=RiDi_HkUIgXtu_33QnRdvYNqcCn-euHUiWwTiPr5IGc,1055
 sqlspec/migrations/base.py,sha256=vIzQzUtQrNKDec6XUeRHcCBuWU1KNtRCFpOvVxsp3sQ,13093
@@ -130,9 +130,9 @@ sqlspec/utils/singleton.py,sha256=-j-s6LS0pP_wTEUYIyK2wSdoeIE_tn7O7B-j7_aODRQ,12
 sqlspec/utils/sync_tools.py,sha256=ksfxsvFb1hLrDlxzwdW44OvYgRB0Fr5JDqxswfHwoOs,8744
 sqlspec/utils/text.py,sha256=W97aX77A3NzG795AHjhdX6zqOBDmvLaXLCno2JIugCo,3081
 sqlspec/utils/type_guards.py,sha256=9C4SRebO4JiQrMzcJZFUA0KjSU48G26RmX6lbijyjBg,30476
-sqlspec-0.20.0.dist-info/METADATA,sha256=DzUA9i2QN3IAmijgOMY6sUQ-Ua9GlUqm6fuzMT8JYr8,16822
-sqlspec-0.20.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-sqlspec-0.20.0.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
-sqlspec-0.20.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
-sqlspec-0.20.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
-sqlspec-0.20.0.dist-info/RECORD,,
+sqlspec-0.21.0.dist-info/METADATA,sha256=_mWB33isyFUYPN30oshULbI5KPKA4ztOiY4OoSsnIR8,23548
+sqlspec-0.21.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+sqlspec-0.21.0.dist-info/entry_points.txt,sha256=G-ZqY1Nuuw3Iys7nXw23f6ILenk_Lt47VdK2mhJCWHg,53
+sqlspec-0.21.0.dist-info/licenses/LICENSE,sha256=MdujfZ6l5HuLz4mElxlu049itenOR3gnhN1_Nd3nVcM,1078
+sqlspec-0.21.0.dist-info/licenses/NOTICE,sha256=Lyir8ozXWov7CyYS4huVaOCNrtgL17P-bNV-5daLntQ,1634
+sqlspec-0.21.0.dist-info/RECORD,,