fix(database): normalise asyncpg to psycopg in get_url

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

Author: olivermeyer

ATTRIBUTIONS.md

@@ -360,7 +360,7 @@ SOFTWARE.
 
 ```
 
-## aignostics-foundry-core (0.6.1) - MIT License
+## aignostics-foundry-core (0.6.2) - MIT License
 
 🏭 Foundational infrastructure for Foundry components.
 

docs/decisions/0004-databasesettings-url-attribute.md

@@ -0,0 +1,48 @@
+# 4. DatabaseSettings URL attribute
+
+Date: 2026-04-02
+
+## Status
+
+Accepted
+
+## Context
+
+The functionality of the `DatabaseSettings` class is inherited from Bridge. It has:
+- A `url` field to store the full database connection URL, including a driver prefix and database name
+- A `name` field to store just the database name for substitution (used for feature environments)
+- A `get_url()` method that processes the raw URL (optionally replacing the driver and database name) and is the
+intended API for consumers
+
+This is confusing: it's not clear that the URL should contain a database name, nor that the driver in the URL might be
+replaced at runtime, nor that the `name` field is used for substitution. Additionally, callers might easily reach
+for `settings.url` instead of `settings.get_url()`, skipping the processing logic and causing subtle bugs.
+
+### Alternatives
+
+- Rename `url` to `_url` with `Field(alias="url")`: this would make it clear that it's an internal field,
+but is **not supported by Pydantic >= 2.1.0**. We therefore reject this option.
+- Refactor the class to have a `host`, `db_name` and optional `driver` attributes and always construct the URL at runtime.
+This is the preferred design, but is a more significant change which would delay delivery of the service template.
+We therefore reject this option **for now**.
+- **`raw_url: SecretStr = Field(alias="url")`**: pydantic-settings applies the dynamic
+  `_env_prefix` only to field names, not to aliases. With prefix `TEST_DB_` and
+  `Field(alias="url")`, pydantic-settings looks for the bare env var `URL` rather than
+  `TEST_DB_URL`, breaking the env-var contract entirely. `validate_by_name=True` adds a lookup
+  for `TEST_DB_RAW_URL` but never for `TEST_DB_URL`. `PrivateAttr` was also evaluated: it
+  supports underscore names but cannot be populated from env vars by pydantic-settings, requiring
+  a bridge field that still leaves the raw URL accessible.
+
+## Decision
+
+Keep `url: SecretStr` as the field name. Rely on docstrings, the class API design, and this
+decision record to guide callers toward `get_url()`.
+
+## Consequences
+
+- `get_url()` is the only correct way to consume the URL; `settings.url` remains accessible but
+  is clearly documented as internal and unprocessed.
+- The `raw_url` rename and `_url` alias approaches are ruled out; this document records the
+  constraints for future reference.
+- A long-term redesign (separate `host`, `db_name`, optional `driver` fields) remains the preferred
+  direction but is deferred.

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 database `name` substitution); `init_engine(db_url=None, pool_size=None, pool_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()` |
+| **database** | Async SQLAlchemy session management + DB settings | `DatabaseSettings` (`OpaqueSettings` subclass; env prefix defaults to `{ctx.env_prefix}DB_`; `url: SecretStr` (required; always access via `get_url()`, not directly); `get_url()` with optional database `name` substitution); `init_engine(db_url=None, pool_size=None, pool_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                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
@@ -220,7 +220,7 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 - **Purpose**: Provides a self-contained `OpaqueSettings` subclass that reads database connection parameters from env vars. The env prefix defaults to `{FoundryContext.env_prefix}DB_` when not supplied, enabling zero-boilerplate DB configuration once a `FoundryContext` is installed.
 - **Key Features**:
-  - `DatabaseSettings(OpaqueSettings)` — fields: `url: SecretStr` (required), `pool_size: int = 10`, `pool_max_overflow: int = 10`, `pool_timeout: float = 30.0`, `name: str | None = None`
+  - `DatabaseSettings(OpaqueSettings)` — fields: `url: SecretStr` (required; use `get_url()` — do not access `url` directly), `pool_size: int = 10`, `pool_max_overflow: int = 10`, `pool_timeout: float = 30.0`, `name: str | None = None`
   - `__init__(_env_prefix=None, **kwargs)` — when `_env_prefix` is `None`, lazy-imports `get_context` and uses `f"{ctx.env_prefix}DB_"` as the prefix (avoids a circular import at module load time)
   - `get_url() -> str` — returns the raw URL from the secret; if `name` is set, replaces the path component in the URL (e.g. `…/postgres` → `…/mydb`) while preserving scheme, host, port, query, and fragment
   - `model_config = SettingsConfigDict(extra="ignore")` — extra env vars are silently ignored

src/aignostics_foundry_core/database.py

@@ -36,11 +36,14 @@ class DatabaseSettings(OpaqueSettings):
 
     Environment variables (with default prefix ``{NAME}_DB_``):
 
-    * ``{PREFIX}URL`` — required; the full database connection URL
+    * ``{PREFIX}URL`` — required; the full database connection URL. Access via :meth:`get_url` only.
     * ``{PREFIX}POOL_SIZE`` — optional; connection pool size (default ``10``)
     * ``{PREFIX}POOL_MAX_OVERFLOW`` — optional; maximum pool overflow (default ``10``)
     * ``{PREFIX}POOL_TIMEOUT`` — optional; pool checkout timeout in seconds (default ``30.0``)
     * ``{PREFIX}NAME`` — optional; override the database name in the URL path component
+
+    References:
+        docs/decisions/0004-databasesettings-url-attribute.md
     """
 
     model_config = SettingsConfigDict(extra="ignore")
@@ -59,6 +62,10 @@ def __init__(
     ) -> None:
         """Initialise settings, deriving env prefix and env files from the active FoundryContext when not given.
 
+        TODO(oliverm): should this class have a `host` attribute WITHOUT the DB name, and construct the full URL as
+          `host/name`? This would avoid the confusion between the `url` attribute and the `get_url()` method.
+          See docs/decisions/0004-databasesettings-url-attribute.md.
+
         Args:
             _env_prefix: Optional explicit environment variable prefix (e.g. ``"MYAPP_DB_"``).
                 When ``None``, the prefix is derived from the active FoundryContext as
@@ -92,15 +99,16 @@ def __init__(
             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.
+        """Return the database URL string, normalizing the driver and optionally substituting the database name.
 
-        When :attr:`name` is set, the path component of the URL is replaced with
-        ``/{name}``, leaving the scheme, host, port, query, and fragment unchanged.
+        The method performs two transformations:
+        1. Normalizes ``+asyncpg`` driver to ``+psycopg`` in the URL scheme
+        2. When :attr:`name` is set, replaces the path component with ``/{name}``
 
         Returns:
-            The database URL as a plain string.
+            The database URL as a plain string with normalized driver.
         """
-        raw = self.url.get_secret_value()
+        raw = self.url.get_secret_value().replace("+asyncpg", "+psycopg")
         if self.name is None:
             return raw
         parsed = urllib.parse.urlparse(raw)

tests/aignostics_foundry_core/database_settings_test.py

@@ -11,6 +11,7 @@
 
 # Constants (SonarQube S1192)
 POSTGRES_URL = "postgresql+asyncpg://user:pass@localhost:5432/postgres"
+POSTGRES_URL_PSYCOPG = "postgresql+psycopg://user:pass@localhost:5432/postgres"
 SQLITE_URL = "sqlite+aiosqlite:///test.db"
 WRONG_SQLITE_URL = "sqlite+aiosqlite:///wrong.db"
 MYAPP_ENV_PREFIX = "MYAPP_"
@@ -44,7 +45,7 @@ def _reset_context() -> Generator[None, None, None]:  # pyright: ignore[reportUn
 def test_get_url_returns_plain_url_when_db_name_not_set() -> None:
     """get_url() returns the raw secret value unchanged when database name is None."""
     settings = DatabaseSettings(_env_prefix="TEST_DB_", url=POSTGRES_URL)
-    assert settings.get_url() == POSTGRES_URL
+    assert settings.get_url() == POSTGRES_URL_PSYCOPG
 
 
 @pytest.mark.unit
@@ -61,10 +62,26 @@ def test_get_url_preserves_scheme_and_host() -> None:
     """Scheme, host, and port are intact after name substitution."""
     settings = DatabaseSettings(_env_prefix="TEST_DB_", url=POSTGRES_URL, name="mydb")
     result = settings.get_url()
-    assert result.startswith("postgresql+asyncpg://")
+    assert result.startswith("postgresql+psycopg://")
     assert "localhost:5432" in result
 
 
+@pytest.mark.unit
+def test_get_url_normalises_asyncpg_to_psycopg() -> None:
+    """get_url() rewrites +asyncpg to +psycopg in the returned URL."""
+    settings = DatabaseSettings(_env_prefix="TEST_DB_", url=POSTGRES_URL)
+    result = settings.get_url()
+    assert "+asyncpg" not in result
+    assert "+psycopg" in result
+
+
+@pytest.mark.unit
+def test_get_url_leaves_non_asyncpg_schemes_unchanged() -> None:
+    """get_url() does not modify URLs that do not contain +asyncpg."""
+    settings = DatabaseSettings(_env_prefix="TEST_DB_", url=SQLITE_URL)
+    assert settings.get_url() == SQLITE_URL
+
+
 # ---------------------------------------------------------------------------
 # env-prefix resolution
 # ---------------------------------------------------------------------------
@@ -78,7 +95,7 @@ def test_default_env_prefix_reads_from_context(monkeypatch: pytest.MonkeyPatch)
     monkeypatch.setenv("MYAPP_DB_URL", POSTGRES_URL)
 
     settings = DatabaseSettings()
-    assert settings.get_url() == POSTGRES_URL
+    assert settings.get_url() == POSTGRES_URL_PSYCOPG
 
 
 @pytest.mark.unit
@@ -90,7 +107,7 @@ def test_explicit_env_prefix_overrides_context(monkeypatch: pytest.MonkeyPatch)
     monkeypatch.setenv(CUSTOM_PREFIX_URL_ENV, POSTGRES_URL)
 
     settings = DatabaseSettings(_env_prefix=CUSTOM_PREFIX)
-    assert settings.get_url() == POSTGRES_URL
+    assert settings.get_url() == POSTGRES_URL_PSYCOPG
 
 
 # ---------------------------------------------------------------------------
@@ -139,8 +156,8 @@ def test_db_name_reads_from_name_env_var(monkeypatch: pytest.MonkeyPatch) -> Non
 
 
 @pytest.mark.unit
-def test_url_is_masked_in_repr() -> None:
-    """repr(settings) / str(settings) does not expose the raw URL."""
+def test_raw_url_is_masked_in_repr() -> None:
+    """repr(settings) does not expose the secret value of raw_url."""
     settings = DatabaseSettings(_env_prefix="TEST_DB_", url=POSTGRES_URL)
     representation = repr(settings)
     assert "pass" not in representation