feat(database): context-aware defaults for all public fns

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: olivermeyer

README.md

@@ -81,6 +81,51 @@ All public library functions (`logging_initialize`, `sentry_initialize`, `boot`,
 `load_modules`, etc.) accept an optional `context` keyword argument and fall
 back to `get_context()` when it is `None`.
 
+### Database
+
+Once a context is configured via `set_context()`, all database functions work
+with no arguments — the URL and pool settings are read from the context:
+
+```python
+from aignostics_foundry_core.database import init_engine, cli_run_with_db, with_engine
+
+# Zero-arg engine init — reads MYPROJECT_DB_URL, _DB_POOL_SIZE, etc. from env
+init_engine()
+
+# CLI helper — initialises engine, runs coroutine, disposes engine
+cli_run_with_db(my_async_func)
+
+
+# Background job decorator — engine initialised before each invocation
+@with_engine
+async def my_job(): ...
+
+
+# Override for a secondary database
+@with_engine(db_url="postgresql+asyncpg://user:pass@host/secondary")
+async def my_other_job(): ...
+```
+
+`FoundryContext.from_package()` activates database configuration automatically
+when the following environment variables are present:
+
+| Variable | Required | Description |
+|---|---|---|
+| `{PREFIX}DB_URL` | yes (to activate) | Full database connection URL |
+| `{PREFIX}DB_POOL_SIZE` | no | Connection pool size (default `10`) |
+| `{PREFIX}DB_MAX_OVERFLOW` | no | Max pool overflow (default `10`) |
+| `{PREFIX}DB_POOL_TIMEOUT` | no | Pool wait timeout in seconds (default `30.0`) |
+| `{PREFIX}DB_NAME` | no | Override database name in the URL path |
+
+In tests, construct `DatabaseSettings` directly instead of setting env vars:
+
+```python
+from aignostics_foundry_core.database import DatabaseSettings
+from tests.conftest import make_context
+
+ctx = make_context(database=DatabaseSettings(_env_prefix="TEST_DB_", url="sqlite+aiosqlite:///test.db"))
+```
+
 ### Health API
 
 ```python

src/aignostics_foundry_core/AGENTS.md

@@ -17,7 +17,7 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 | **log** | Configurable loguru logging initialisation | `logging_initialize(filter_func=None, *, context=None)`, `LogSettings` (env-prefix configurable), `InterceptHandler` for stdlib-to-loguru bridging |
 | **sentry** | Configurable Sentry integration | `sentry_initialize(integrations, *, context=None)`, `SentrySettings` (env-prefix configurable), `set_sentry_user(user, role_claim)` for Auth0 user context |
 | **service** | FastAPI-injectable base service | `BaseService` ABC with `get_service()` (cached per-class FastAPI `Depends` factory), `key()`, and abstract `health()` / `info()` methods; concrete subclasses implement health checks and module info |
-| **database** | Async SQLAlchemy session management + DB settings | `DatabaseSettings` (`OpaqueSettings` subclass; env prefix defaults to `{ctx.env_prefix}DB_`; `get_url()` with optional `db_name` substitution); `init_engine(db_url, pool_size, max_overflow, pool_timeout)`, `dispose_engine()`, `get_db_session()` (FastAPI dependency), `execute_with_session(func, …)`, `cli_run_with_db(func, …, db_url)`, `cli_run_with_engine(func, …, db_url)`, `with_engine(db_url)` decorator factory; auto-resets engine after `fork()` |
+| **database** | Async SQLAlchemy session management + DB settings | `DatabaseSettings` (`OpaqueSettings` subclass; env prefix defaults to `{ctx.env_prefix}DB_`; `get_url()` with optional `db_name` substitution); `init_engine(db_url=None, pool_size=None, max_overflow=None, pool_timeout=None)` — all params optional, fall back to active context when `None`; `dispose_engine()`, `get_db_session()` (FastAPI dependency), `execute_with_session(func, …)`, `cli_run_with_db(func, …, db_url=None)`, `cli_run_with_engine(func, …, db_url=None)`, `with_engine` dual-mode decorator (supports `@with_engine`, `@with_engine()`, `@with_engine(db_url=…)`); auto-resets engine after `fork()` |
 | **cli** | Typer CLI preparation utilities | `prepare_cli(cli, epilog, *, context=None)` — discovers and registers subcommands via `locate_implementations`, sets epilog recursively, installs `no_args_is_help` workaround; `no_args_is_help_workaround(ctx)` — raises `typer.Exit` when no subcommand is invoked |
 | **boot** | Application / library boot sequence | `boot(context, sentry_integrations, log_filter, show_cmdline)` — runs once per process: parses `--env` CLI args, initialises logging and Sentry, amends the SSL trust chain via *truststore* and *certifi*, and logs boot/shutdown messages |
 | **user_agent** | Parameterised HTTP user-agent string builder | `user_agent(project_name, version, repository_url)` — builds `{project_name}-python-sdk/{version} (…)` string including platform info, current test, and GitHub Actions run URL |
@@ -321,15 +321,15 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 **Async SQLAlchemy session management**
 
-- **Purpose**: Manages a process-level async database engine singleton, providing session injection for FastAPI routes, background jobs, and CLI commands. All Bridge-specific settings are replaced with explicit parameters.
+- **Purpose**: Manages a process-level async database engine singleton, providing session injection for FastAPI routes, background jobs, and CLI commands. All public functions accept optional DB-config params and fall back to the active `FoundryContext.database` when they are `None`.
 - **Key Features**:
-  - `init_engine(db_url, pool_size=10, max_overflow=10, pool_timeout=30)` — initialises the global `AsyncEngine` and `async_sessionmaker`; subsequent calls are silent no-ops. Pool parameters are omitted automatically for SQLite (which does not use `QueuePool`).
+  - `init_engine(db_url=None, pool_size=None, max_overflow=None, pool_timeout=None)` — initialises the global `AsyncEngine` and `async_sessionmaker`; subsequent calls are silent no-ops. When `db_url` is `None`, the URL and pool settings are resolved from `get_context().database`; raises `RuntimeError` if no context is installed or `ctx.database` is `None`. Pool parameters are omitted automatically for SQLite (which does not use `QueuePool`).
   - `dispose_engine()` — async; disposes the engine; called during application shutdown.
   - `get_db_session()` — async generator; yields an `AsyncSession`; raises `RuntimeError` if engine not initialised. Use as a FastAPI `Depends` target.
   - `execute_with_session(async_func, *args, **kwargs)` — async; runs `async_func` with a session injected as the `session` keyword argument. For background jobs and CLI helpers.
-  - `cli_run_with_db(async_func, *args, db_url, pool_size, max_overflow, pool_timeout, **kwargs)` — synchronous wrapper: initialises engine, runs the coroutine, then disposes. For CLI commands.
-  - `cli_run_with_engine(async_func, *args, db_url, pool_size, max_overflow, pool_timeout, **kwargs)` — like `cli_run_with_db` but does not inject a session; for jobs that manage sessions themselves.
-  - `with_engine(db_url, pool_size, max_overflow, pool_timeout)` — decorator factory; wraps an async function to initialise the engine before execution. For long-lived workers; does **not** dispose after running.
+  - `cli_run_with_db(async_func, *args, db_url=None, pool_size=None, max_overflow=None, pool_timeout=None, **kwargs)` — synchronous wrapper: initialises engine, runs the coroutine, then disposes. All DB-config params optional; fall back to context when `None`. For CLI commands.
+  - `cli_run_with_engine(async_func, *args, db_url=None, pool_size=None, max_overflow=None, pool_timeout=None, **kwargs)` — like `cli_run_with_db` but does not inject a session; for jobs that manage sessions themselves.
+  - `with_engine` — dual-mode decorator; supports `@with_engine` (no-parens), `@with_engine()` (empty parens), and `@with_engine(db_url=…, …)` (explicit params). All params optional; fall back to context when absent. For long-lived workers; does **not** dispose after running.
   - Fork safety: `multiprocessing.util.register_after_fork` resets the engine in child processes automatically.
 - **Location**: `aignostics_foundry_core/database.py`
 - **Dependencies**: `sqlalchemy[asyncio]>=2,<3`, `asyncpg>=0.29,<1` (mandatory); `loguru` for structured logging

src/aignostics_foundry_core/database.py

@@ -14,7 +14,7 @@
 import functools
 import multiprocessing.util
 import urllib.parse
-from collections.abc import AsyncGenerator, Callable
+from collections.abc import AsyncGenerator
 from typing import Any
 
 from loguru import logger
@@ -120,11 +120,56 @@ class _DatabaseModuleSentinel:
 multiprocessing.util.register_after_fork(_module_sentinel, lambda _obj: _reset_engine_after_fork())
 
 
+_DEFAULT_POOL_SIZE = 10
+_DEFAULT_MAX_OVERFLOW = 10
+_DEFAULT_POOL_TIMEOUT = 30.0
+
+
+def _resolve_db_params(
+    db_url: str | None,
+    pool_size: int | None,
+    max_overflow: int | None,
+    pool_timeout: float | None,
+) -> tuple[str, int, int, float]:
+    """Resolve database connection parameters, falling back to the active context.
+
+    When ``db_url`` is ``None``, all four values are sourced from
+    ``get_context().database``.  When ``db_url`` is provided, any ``None`` pool
+    params are replaced by their module-level defaults.
+
+    Returns:
+        A tuple of ``(db_url, pool_size, max_overflow, pool_timeout)``.
+
+    Raises:
+        RuntimeError: If ``db_url`` is ``None`` and no context is installed, or
+            the context has no ``database`` configured.
+    """
+    if db_url is None:
+        from aignostics_foundry_core.foundry import get_context  # noqa: PLC0415
+
+        ctx = get_context()
+        if ctx.database is None:
+            msg = f"No database URL configured. Set {ctx.env_prefix}DB_URL or pass db_url explicitly."
+            raise RuntimeError(msg)
+        return (
+            ctx.database.get_url(),
+            pool_size if pool_size is not None else ctx.database.pool_size,
+            max_overflow if max_overflow is not None else ctx.database.max_overflow,
+            pool_timeout if pool_timeout is not None else ctx.database.pool_timeout,
+        )
+    return (
+        db_url,
+        pool_size if pool_size is not None else _DEFAULT_POOL_SIZE,
+        max_overflow if max_overflow is not None else _DEFAULT_MAX_OVERFLOW,
+        pool_timeout if pool_timeout is not None else _DEFAULT_POOL_TIMEOUT,
+    )
+
+
 def init_engine(
-    db_url: str,
-    pool_size: int = 10,
-    max_overflow: int = 10,
-    pool_timeout: float = 30,
+    db_url: str | None = None,
+    pool_size: int | None = None,
+    max_overflow: int | None = None,
+    pool_timeout: float | None = None,
 ) -> None:
     """Initialize the database engine singleton.
 
@@ -135,21 +180,33 @@ def init_engine(
     For multiprocessing: Engine is automatically reset in child processes via
     multiprocessing.util.register_after_fork().
 
+    When ``db_url`` is ``None``, the URL and pool settings are resolved from the
+    active :class:`~aignostics_foundry_core.foundry.FoundryContext`.  A
+    :exc:`RuntimeError` is raised if no context is installed or the context has no
+    ``database`` configured.
+
     Args:
         db_url: Database connection URL (e.g. ``postgresql+asyncpg://user:pass@host/db``).
+            When ``None``, resolved from the active context's ``database`` settings.
         pool_size: Number of connections to keep in the pool. Ignored for dialects that
-            do not support QueuePool (e.g. SQLite).
+            do not support QueuePool (e.g. SQLite).  Defaults to the context value or 10.
         max_overflow: Number of additional connections above pool_size. Ignored for
-            dialects that do not support QueuePool.
+            dialects that do not support QueuePool.  Defaults to the context value or 10.
         pool_timeout: Seconds to wait for a connection from the pool. Ignored for
-            dialects that do not support QueuePool.
+            dialects that do not support QueuePool.  Defaults to the context value or 30.
+
+    Raises:
+        RuntimeError: If ``db_url`` is ``None`` and no context is installed, or the
+            context has no ``database`` configured.
     """
     global _engine, _async_session_maker  # noqa: PLW0603
 
     if _engine is not None:
         logger.trace("Database engine already initialized, reusing existing engine and connection pool.")
         return  # Already initialized
 
+    db_url, pool_size, max_overflow, pool_timeout = _resolve_db_params(db_url, pool_size, max_overflow, pool_timeout)
+
     logger.trace(
         "Initializing global database engine with pool_size={}, max_overflow={}, pool_timeout={}",
         pool_size,
@@ -248,10 +305,10 @@ async def execute_with_session(async_func: Any, *args: Any, **kwargs: Any) -> An
 def cli_run_with_db(
     async_func: Any,  # noqa: ANN401
     *args: Any,  # noqa: ANN401
-    db_url: str,
-    pool_size: int = 10,
-    max_overflow: int = 10,
-    pool_timeout: float = 30,
+    db_url: str | None = None,
+    pool_size: int | None = None,
+    max_overflow: int | None = None,
+    pool_timeout: float | None = None,
     **kwargs: Any,  # noqa: ANN401
 ) -> Any:  # noqa: ANN401
     """Run an async database function from a synchronous CLI context.
@@ -261,10 +318,14 @@ def cli_run_with_db(
 
     NOT for use in long-lived processes (API, workers) - use @with_engine decorator instead.
 
+    When ``db_url`` is ``None``, the URL and pool settings are resolved from the active
+    :class:`~aignostics_foundry_core.foundry.FoundryContext` (same behaviour as
+    :func:`init_engine`).
+
     Args:
         async_func: The async function to run (receives ``session`` as a keyword argument).
         *args: Positional arguments forwarded to ``async_func``.
-        db_url: Database connection URL.
+        db_url: Database connection URL.  When ``None``, resolved from the active context.
         pool_size: Connection pool size (ignored for SQLite).
         max_overflow: Max overflow connections (ignored for SQLite).
         pool_timeout: Pool wait timeout in seconds (ignored for SQLite).
@@ -291,10 +352,10 @@ def cli_run_with_db(
 def cli_run_with_engine(
     async_func: Any,  # noqa: ANN401
     *args: Any,  # noqa: ANN401
-    db_url: str,
-    pool_size: int = 10,
-    max_overflow: int = 10,
-    pool_timeout: float = 30,
+    db_url: str | None = None,
+    pool_size: int | None = None,
+    max_overflow: int | None = None,
+    pool_timeout: float | None = None,
     **kwargs: Any,  # noqa: ANN401
 ) -> Any:  # noqa: ANN401
     """Run an async function with initialized database engine from a synchronous CLI context.
@@ -304,10 +365,14 @@ def cli_run_with_engine(
 
     NOT for use in long-lived processes (API, workers) - use @with_engine decorator instead.
 
+    When ``db_url`` is ``None``, the URL and pool settings are resolved from the active
+    :class:`~aignostics_foundry_core.foundry.FoundryContext` (same behaviour as
+    :func:`init_engine`).
+
     Args:
         async_func: The async function to run (does not require a session parameter).
         *args: Positional arguments forwarded to ``async_func``.
-        db_url: Database connection URL.
+        db_url: Database connection URL.  When ``None``, resolved from the active context.
         pool_size: Connection pool size (ignored for SQLite).
         max_overflow: Max overflow connections (ignored for SQLite).
         pool_timeout: Pool wait timeout in seconds (ignored for SQLite).
@@ -331,49 +396,66 @@ def cli_run_with_engine(
 
 
 def with_engine(
-    db_url: str,
-    pool_size: int = 10,
-    max_overflow: int = 10,
-    pool_timeout: float = 30,
-) -> Callable[[Any], Any]:
-    """Decorator factory to ensure database engine is initialized for async functions.
+    func: Any | None = None,  # noqa: ANN401
+    *,
+    db_url: str | None = None,
+    pool_size: int | None = None,
+    max_overflow: int | None = None,
+    pool_timeout: float | None = None,
+) -> Any:  # noqa: ANN401
+    """Decorator (or decorator factory) to ensure database engine is initialized for async functions.
+
+    Supports two calling conventions:
 
-    This decorator wraps an async function to automatically initialize the database
-    engine singleton before execution. The connection pool persists across all jobs
-    in the process for efficiency. Useful for background jobs and workers.
+    * ``@with_engine`` — no-parens form; resolves URL and pool settings from the
+      active :class:`~aignostics_foundry_core.foundry.FoundryContext`.
+    * ``@with_engine()`` or ``@with_engine(db_url=..., ...)`` — explicit-parens form;
+      any omitted params are resolved from the active context.
+
+    The connection pool persists across all jobs in the process for efficiency.
+    Useful for background jobs and workers.
 
     For multiprocessing: Engine is automatically reset in child processes via
     multiprocessing.util.register_after_fork().
 
     Args:
-        db_url: Database connection URL.
+        func: The async function to decorate (only when used as ``@with_engine``
+            without parentheses).  Do not pass explicitly.
+        db_url: Database connection URL.  When ``None``, resolved from the active context.
         pool_size: Connection pool size (ignored for SQLite).
         max_overflow: Max overflow connections (ignored for SQLite).
         pool_timeout: Pool wait timeout in seconds (ignored for SQLite).
 
     Returns:
-        A decorator that wraps an async function with engine initialization.
+        The decorated async function (no-parens form) or a decorator (parens form).
 
-    Example:
-        @with_engine(db_url="postgresql+asyncpg://user:pass@host/db")
+    Example::
+
+        # Context-aware — no arguments needed once set_context() is called:
+        @with_engine
         async def my_job():
             result = await execute_with_session(some_db_operation)
             return result
+
+
+        # Explicit URL (e.g. secondary database):
+        @with_engine(db_url="postgresql+asyncpg://user:pass@host/db")
+        async def my_other_job(): ...
     """
 
-    def decorator(func: Any) -> Any:  # noqa: ANN401
-        func_name = getattr(func, "__name__", str(func))
+    def decorator(f: Any) -> Any:  # noqa: ANN401
+        func_name = getattr(f, "__name__", str(f))
         logger.trace("Applying with_engine decorator to function {}", func_name)
 
-        @functools.wraps(func)
+        @functools.wraps(f)
         async def wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
             logger.trace("Initializing database engine in with_engine wrapper for function {}", func_name)
             init_engine(db_url=db_url, pool_size=pool_size, max_overflow=max_overflow, pool_timeout=pool_timeout)
             logger.debug("Database engine initialized in with_engine wrapper for function {}", func_name)
 
             try:
                 logger.trace("Executing function {} within with_engine wrapper", func_name)
-                result = await func(*args, **kwargs)
+                result = await f(*args, **kwargs)
                 logger.trace("Successfully executed function {} within with_engine wrapper", func_name)
                 return result
             except Exception:
@@ -382,4 +464,6 @@ async def wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
 
         return wrapper
 
-    return decorator
+    if func is not None:  # called as @with_engine (no parens)
+        return decorator(func)
+    return decorator  # called as @with_engine() or @with_engine(db_url=...)