feat(database): resolve env_file from active context in DatabaseSettings

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

Author: olivermeyer

src/aignostics_foundry_core/database.py

@@ -15,6 +15,7 @@
 import multiprocessing.util
 import urllib.parse
 from collections.abc import AsyncGenerator
+from pathlib import Path
 from typing import Any
 
 from loguru import logger
@@ -50,20 +51,45 @@ class DatabaseSettings(OpaqueSettings):
     pool_timeout: float = 30.0
     name: str | None = None
 
-    def __init__(self, _env_prefix: str | None = None, **kwargs: Any) -> None:  # noqa: ANN401
-        """Initialise settings, deriving env prefix from the active FoundryContext when not given.
+    def __init__(
+        self,
+        _env_prefix: str | None = None,
+        _env_file: list[Path] | None = None,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> None:
+        """Initialise settings, deriving env prefix and env files from the active FoundryContext when not given.
 
         Args:
             _env_prefix: Optional explicit environment variable prefix (e.g. ``"MYAPP_DB_"``).
                 When ``None``, the prefix is derived from the active FoundryContext as
                 ``f"{get_context().env_prefix}DB_"``.
+            _env_file: Optional explicit list of ``.env`` files to read settings from.
+                When ``None`` and a :class:`~aignostics_foundry_core.foundry.FoundryContext` is
+                active, the context's :attr:`~aignostics_foundry_core.foundry.FoundryContext.env_file`
+                list is used so that all settings sources remain consistent.  When ``None`` and no
+                context is available (but ``_env_prefix`` is provided explicitly), env-file loading
+                is skipped.
             **kwargs: Forwarded to :class:`~pydantic_settings.BaseSettings`.
+
+        Raises:
+            RuntimeError: If both ``_env_prefix`` is absent and no active context is installed.
         """
-        if _env_prefix is None:
+        if _env_prefix is None or _env_file is None:
             from aignostics_foundry_core.foundry import get_context  # noqa: PLC0415
 
-            _env_prefix = f"{get_context().env_prefix}DB_"
-        super().__init__(_env_prefix=_env_prefix, **kwargs)  # pyright: ignore[reportCallIssue]
+            try:
+                ctx = get_context()
+                if _env_prefix is None:
+                    _env_prefix = f"{ctx.env_prefix}DB_"
+                if _env_file is None:
+                    _env_file = ctx.env_file
+            except RuntimeError:
+                if _env_prefix is None:
+                    raise
+        if _env_file is not None:
+            super().__init__(_env_prefix=_env_prefix, _env_file=_env_file, **kwargs)  # pyright: ignore[reportCallIssue]
+        else:
+            super().__init__(_env_prefix=_env_prefix, **kwargs)  # pyright: ignore[reportCallIssue]
 
     def get_url(self) -> str:
         """Return the database URL string, optionally substituting the database name.

tests/aignostics_foundry_core/database_settings_test.py

@@ -1,6 +1,7 @@
 """Tests for DatabaseSettings."""
 
 from collections.abc import Generator
+from pathlib import Path
 
 import pytest
 
@@ -11,6 +12,9 @@
 # Constants (SonarQube S1192)
 POSTGRES_URL = "postgresql+asyncpg://user:pass@localhost:5432/postgres"
 SQLITE_URL = "sqlite+aiosqlite:///test.db"
+WRONG_SQLITE_URL = "sqlite+aiosqlite:///wrong.db"
+MYAPP_ENV_PREFIX = "MYAPP_"
+MYAPP_DB_URL_KEY = "MYAPP_DB_URL"
 CUSTOM_PREFIX = "CUSTOM_DB_"
 CUSTOM_PREFIX_URL_ENV = "CUSTOM_DB_URL"
 DEFAULT_POOL_SIZE = 10
@@ -141,3 +145,44 @@ def test_url_is_masked_in_repr() -> None:
     representation = repr(settings)
     assert "pass" not in representation
     assert "**" in representation or "SecretStr" in representation
+
+
+# ---------------------------------------------------------------------------
+# env-file resolution via context (integration)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.integration
+def test_database_settings_reads_url_from_env_file_via_context(tmp_path: Path) -> None:
+    """DatabaseSettings() with no args reads URL from context env_file when context is set."""
+    env_file = tmp_path / ".env"
+    env_file.write_text(f"{MYAPP_DB_URL_KEY}={SQLITE_URL}\n")
+
+    ctx = make_context(env_prefix=MYAPP_ENV_PREFIX, env_file=[env_file])
+    set_context(ctx)
+
+    settings = DatabaseSettings()
+    assert settings.get_url() == SQLITE_URL
+
+
+@pytest.mark.integration
+def test_database_settings_explicit_env_file_overrides_context(tmp_path: Path) -> None:
+    """An explicit _env_file passed to DatabaseSettings() takes precedence over the context env_file."""
+    context_env_file = tmp_path / "context.env"
+    context_env_file.write_text(f"{MYAPP_DB_URL_KEY}={WRONG_SQLITE_URL}\n")
+
+    explicit_env_file = tmp_path / "explicit.env"
+    explicit_env_file.write_text(f"{MYAPP_DB_URL_KEY}={SQLITE_URL}\n")
+
+    ctx = make_context(env_prefix=MYAPP_ENV_PREFIX, env_file=[context_env_file])
+    set_context(ctx)
+
+    settings = DatabaseSettings(_env_file=[explicit_env_file])
+    assert settings.get_url() == SQLITE_URL
+
+
+@pytest.mark.integration
+def test_database_settings_no_context_raises_without_prefix() -> None:
+    """DatabaseSettings() raises RuntimeError when no context is installed and no prefix is given."""
+    with pytest.raises(RuntimeError, match="get_context\\(\\) called before set_context"):
+        DatabaseSettings()

tests/conftest.py

@@ -70,6 +70,7 @@ def make_context(  # noqa: PLR0913
     project_path: Path | None = None,
     repository_url: str = "",
     database: DatabaseSettings | None = None,
+    env_file: list[Path] | None = None,
     **kwargs: bool,
 ) -> FoundryContext:
     """Create a minimal FoundryContext for testing.
@@ -83,6 +84,7 @@ def make_context(  # noqa: PLR0913
         repository_url: The project repository URL (defaults to ``""``).
         database: Optional :class:`~aignostics_foundry_core.database.DatabaseSettings`
             instance to attach to the context.
+        env_file: Optional list of ``.env`` file paths to attach to the context.
         **kwargs: Optional boolean flags forwarded to :class:`FoundryContext`
             (``is_test``, ``is_cli``, ``is_container``, ``is_library``).
     """
@@ -96,5 +98,6 @@ def make_context(  # noqa: PLR0913
         project_path=project_path,
         repository_url=repository_url,
         database=database,
+        env_file=env_file or [],
         **kwargs,  # type: ignore[arg-type]
     )