feat(config): accept provider connection strings verbatim and translate libpq SSL params

Author: codebybilal18

.env.example

@@ -9,8 +9,11 @@ DATABASE_URL=postgresql+asyncpg://documind:documind@localhost:5432/documind
 # Host port for the compose Postgres. Change if you already run Postgres on 5432,
 # and update DATABASE_URL to match.
 POSTGRES_PORT=5432
-# Neon: use the POOLED connection string on serverless and add ?sslmode=require
-# DATABASE_URL=postgresql+asyncpg://user:pass@ep-xxx-pooler.region.aws.neon.tech/documind
+# Neon / Supabase / Render: paste the connection string exactly as the console
+# gives it to you. The driver is corrected and libpq-only parameters
+# (sslmode, channel_binding) are translated automatically — see
+# Settings._normalise_database_url. Use the POOLED host on serverless.
+# DATABASE_URL=postgresql://user:pass@ep-xxx-pooler.region.aws.neon.tech/db?sslmode=require
 
 # --- OpenAI -----------------------------------------------------------------
 OPENAI_API_KEY=sk-...

app/config.py

@@ -12,7 +12,7 @@
 from functools import lru_cache
 from typing import Literal
 
-from pydantic import BaseModel
+from pydantic import BaseModel, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -102,6 +102,9 @@ class Settings(BaseSettings):
     # Neon: use the *pooled* connection string on serverless.
     # Must be the asyncpg driver: postgresql+asyncpg://...
     database_url: str = "postgresql+asyncpg://documind:documind@localhost:5432/documind"
+    # Set from the URL's libpq params by the validator below; asyncpg takes SSL
+    # as a connect argument, not a query string.
+    database_ssl: str | None = None
 
     # --- OpenAI -------------------------------------------------------------
     openai_api_key: str = ""
@@ -162,6 +165,80 @@ class Settings(BaseSettings):
     cors_origins: str = "*"
     api_key: str | None = None  # optional shared-secret gate for write endpoints
 
+    @model_validator(mode="after")
+    def _normalise_database_url(self) -> Settings:
+        """Accept a connection string copied verbatim from a provider console.
+
+        Neon, Supabase and Render all hand you a libpq URL:
+
+            postgresql://user:pw@host/db?sslmode=require&channel_binding=require
+
+        Two things make that unusable here. The scheme selects psycopg, not
+        asyncpg. And `sslmode`/`channel_binding` are libpq parameters — asyncpg
+        does not accept them and raises `TypeError: connect() got an unexpected
+        keyword argument 'sslmode'`, which reads like a code bug rather than a
+        config one.
+
+        Rather than document a hand-edit that everyone will get wrong once, the
+        URL is normalised here: driver corrected, libpq-only parameters lifted
+        out, and SSL carried across as an asyncpg connect argument.
+        """
+        from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+        url = self.database_url.strip()
+        if not url:
+            return self
+
+        parts = urlsplit(url)
+
+        scheme = parts.scheme
+        if scheme in ("postgres", "postgresql"):
+            scheme = "postgresql+asyncpg"
+        elif scheme.startswith("postgresql+") and scheme != "postgresql+asyncpg":
+            # A sync driver here would fail much later, inside the engine.
+            raise ValueError(
+                f"DATABASE_URL must use the asyncpg driver, got {parts.scheme!r}. "
+                "Use postgresql+asyncpg://…"
+            )
+
+        # libpq spellings asyncpg cannot take as query parameters.
+        ssl_mode = self.database_ssl
+        kept: list[tuple[str, str]] = []
+        for key, value in parse_qsl(parts.query, keep_blank_values=True):
+            lowered = key.lower()
+            if lowered in ("sslmode", "ssl"):
+                ssl_mode = value or ssl_mode
+            elif lowered == "channel_binding":
+                # asyncpg negotiates channel binding itself; the parameter has
+                # no equivalent and is safe to drop.
+                continue
+            else:
+                kept.append((key, value))
+
+        object.__setattr__(
+            self,
+            "database_url",
+            urlunsplit((scheme, parts.netloc, parts.path, urlencode(kept), parts.fragment)),
+        )
+        # Managed Postgres is TLS-only; default to requiring it for any remote
+        # host so a stripped `sslmode` cannot silently downgrade the connection.
+        if ssl_mode is None and parts.hostname not in (None, "localhost", "127.0.0.1", "db"):
+            ssl_mode = "require"
+        object.__setattr__(self, "database_ssl", ssl_mode)
+        return self
+
+    def asyncpg_connect_args(self) -> dict:
+        """Driver arguments shared by the app engine and Alembic."""
+        args: dict = {
+            # Neon's pooler runs in transaction mode, which is incompatible
+            # with asyncpg's prepared-statement cache.
+            "statement_cache_size": 0,
+            "prepared_statement_cache_size": 0,
+        }
+        if self.database_ssl and self.database_ssl != "disable":
+            args["ssl"] = self.database_ssl
+        return args
+
     @property
     def is_serverless(self) -> bool:
         return self.environment == "vercel"

app/db/migrations/env.py

@@ -41,7 +41,7 @@ async def run_async_migrations() -> None:
         config.get_section(config.config_ini_section, {}),
         prefix="sqlalchemy.",
         poolclass=pool.NullPool,
-        connect_args={"statement_cache_size": 0, "prepared_statement_cache_size": 0},
+        connect_args=settings.asyncpg_connect_args(),
     )
     async with connectable.connect() as connection:
         await connection.run_sync(do_run_migrations)

app/db/session.py

@@ -30,9 +30,7 @@ def _build_engine() -> AsyncEngine:
     kwargs: dict = {
         "echo": False,
         "pool_pre_ping": True,
-        # Neon's pooler runs in transaction mode, which is incompatible with
-        # prepared-statement caching in asyncpg.
-        "connect_args": {"statement_cache_size": 0, "prepared_statement_cache_size": 0},
+        "connect_args": settings.asyncpg_connect_args(),
     }
     if settings.is_serverless:
         kwargs["poolclass"] = NullPool

tests/test_config.py

@@ -0,0 +1,84 @@
+"""Database URL normalisation.
+
+Provider consoles hand out libpq URLs. Pasting one verbatim used to fail deep
+inside asyncpg with `TypeError: connect() got an unexpected keyword argument
+'sslmode'` — an error that reads like a code bug and sends you looking in the
+wrong place entirely.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from app.config import Settings
+
+
+def build(url: str) -> Settings:
+    # _env_file=None keeps a developer's real .env out of the assertions.
+    return Settings(database_url=url, _env_file=None)
+
+
+def test_a_neon_url_pasted_verbatim_is_usable():
+    s = build(
+        "postgresql://user:pw@ep-x-pooler.ap-southeast-1.aws.neon.tech/db"
+        "?sslmode=require&channel_binding=require"
+    )
+
+    assert s.database_url == (
+        "postgresql+asyncpg://user:pw@ep-x-pooler.ap-southeast-1.aws.neon.tech/db"
+    )
+    assert s.database_ssl == "require"
+    assert s.asyncpg_connect_args()["ssl"] == "require"
+
+
+@pytest.mark.parametrize("scheme", ["postgres", "postgresql"])
+def test_the_sync_scheme_is_upgraded_to_asyncpg(scheme):
+    s = build(f"{scheme}://user:pw@localhost:5432/db")
+    assert s.database_url.startswith("postgresql+asyncpg://")
+
+
+def test_an_explicit_sync_driver_is_rejected_loudly():
+    """psycopg here would fail much later, inside engine creation, with a far
+    less obvious message."""
+    with pytest.raises(ValueError, match="asyncpg"):
+        build("postgresql+psycopg://user:pw@localhost/db")
+
+
+def test_an_already_correct_url_is_left_alone():
+    url = "postgresql+asyncpg://documind:documind@localhost:5432/documind"
+    assert build(url).database_url == url
+
+
+def test_channel_binding_is_dropped_but_other_params_survive():
+    s = build("postgresql://u:p@host/db?channel_binding=require&application_name=documind")
+
+    assert "channel_binding" not in s.database_url
+    assert "application_name=documind" in s.database_url
+
+
+def test_a_remote_host_defaults_to_requiring_tls():
+    """A stripped sslmode must not silently downgrade a managed connection."""
+    s = build("postgresql://u:p@ep-x.aws.neon.tech/db")
+    assert s.database_ssl == "require"
+    assert s.asyncpg_connect_args()["ssl"] == "require"
+
+
+@pytest.mark.parametrize("host", ["localhost", "127.0.0.1", "db"])
+def test_local_hosts_do_not_get_tls_forced(host):
+    """docker compose Postgres speaks plaintext; requiring TLS would break it."""
+    s = build(f"postgresql://u:p@{host}:5432/db")
+    assert s.database_ssl is None
+    assert "ssl" not in s.asyncpg_connect_args()
+
+
+def test_sslmode_disable_is_honoured():
+    s = build("postgresql://u:p@remote.example.com/db?sslmode=disable")
+    assert "ssl" not in s.asyncpg_connect_args()
+
+
+def test_the_prepared_statement_cache_is_always_disabled():
+    """Neon's pooler runs in transaction mode; asyncpg's statement cache breaks
+    against it."""
+    args = build("postgresql://u:p@localhost/db").asyncpg_connect_args()
+    assert args["statement_cache_size"] == 0
+    assert args["prepared_statement_cache_size"] == 0