fix(postgres): default SSL mode to 'prefer' for broader compatibility

PostgresBackend previously defaulted to ssl=True, which forced SSL
negotiation. Servers without TLS certificates (Docker, local dev,
private cloud networks) rejected the connection outright.

Now defaults to ssl="prefer": tries SSL first, falls back to plaintext
on rejection. Matches the standard libpq default. Accepts string modes
("prefer", "require", "disable", "verify-full") with True/False backward
compat. DSN-level sslmode= always takes precedence.

Author: bradleygauthier

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.2] - 2026-04-09
+
+### Fixed
+- **PostgresBackend SSL: sslmode=prefer by default**. Previously defaulted to `ssl=True` which forced SSL negotiation. Servers without TLS certificates (Docker, local dev, private cloud networks) rejected the connection. Now defaults to `ssl="prefer"`: try SSL first, fall back to plaintext on rejection. Matches the standard `libpq` default behavior.
+
+### Changed
+- `PostgresBackend.__init__()` `ssl` parameter: `bool` (default `True`) to `str` (default `"prefer"`). Accepts `"prefer"`, `"require"`, `"disable"`, `"verify-full"`, `"verify-ca"`. `True`/`False` still accepted for backward compat.
+- DSN-level `sslmode=` always takes precedence over the constructor `ssl` argument.
+- 5 new tests for SSL mode normalization and backward compatibility.
+
 ## [1.5.1] - 2026-04-08
 
 ### Fixed

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qp-vault"
-version = "1.5.1"
+version = "1.5.2"
 description = "Governed knowledge store for autonomous organizations. Trust tiers, cryptographic audit trails, content-addressed storage, air-gap native."
 readme = "README.md"
 license = "Apache-2.0"

src/qp_vault/__init__.py

@@ -26,7 +26,7 @@
 Docs: https://github.com/quantumpipes/vault
 """
 
-__version__ = "1.5.1"
+__version__ = "1.5.2"
 __author__ = "Quantum Pipes Technologies, LLC"
 __license__ = "Apache-2.0"
 

src/qp_vault/storage/postgres.py

@@ -194,9 +194,20 @@ def __init__(
         *,
         embedding_dimensions: int = 768,
         command_timeout: float = 30.0,
-        ssl: bool = True,
+        ssl: str = "prefer",
         ssl_verify: bool = False,
     ) -> None:
+        """Initialize PostgresBackend.
+
+        Args:
+            dsn: PostgreSQL connection string (``postgresql://user:pass@host/db``).
+            embedding_dimensions: Vector dimensions for pgvector columns.
+            command_timeout: Statement timeout in seconds.
+            ssl: SSL mode. Supports ``"prefer"`` (try SSL, fall back to plaintext),
+                ``"require"`` (SSL required), ``"disable"`` (no SSL), or ``True``/``False``
+                for backward compat. ``sslmode=`` in the DSN always takes precedence.
+            ssl_verify: When True, verify the server certificate against the system CA store.
+        """
         if not HAS_ASYNCPG:
             raise ImportError(
                 "asyncpg is required for PostgresBackend. "
@@ -205,37 +216,72 @@ def __init__(
         self._dsn = dsn
         self._dimensions = embedding_dimensions
         self._command_timeout = command_timeout
-        self._ssl = ssl
+        # Normalize ssl param: True -> "prefer", False -> "disable"
+        if ssl is True:
+            self._ssl_mode = "prefer"
+        elif ssl is False:
+            self._ssl_mode = "disable"
+        else:
+            self._ssl_mode = ssl
         self._ssl_verify = ssl_verify
         self._pool: Any = None
 
     async def _get_pool(self) -> Any:
-        """Get or create connection pool."""
-        if self._pool is None:
-            import ssl as _ssl
+        """Get or create connection pool.
+
+        SSL behavior follows the ``sslmode`` parameter from the DSN if present,
+        otherwise falls back to the ``ssl`` constructor argument (default: ``prefer``).
 
-            ssl_context: Any = None
+        ``prefer`` mode: attempt SSL first; on failure, retry without SSL.
+        This matches the default behavior of libpq and psycopg.
+        """
+        if self._pool is None:
+            # DSN-level sslmode takes precedence over constructor arg
             if "sslmode=disable" in self._dsn:
-                ssl_context = False
-            elif self._ssl:
-                ssl_context = _ssl.create_default_context()
-                if not self._ssl_verify:
-                    ssl_context.check_hostname = False
-                    ssl_context.verify_mode = _ssl.CERT_NONE
-
-            pool_kwargs: dict[str, Any] = {
-                "min_size": 2,
-                "max_size": 10,
-                "command_timeout": self._command_timeout,
-            }
-            if ssl_context is not None and ssl_context is not False:
-                pool_kwargs["ssl"] = ssl_context
-            elif ssl_context is False:
-                pass  # Explicitly disabled via DSN
-
-            self._pool = await asyncpg.create_pool(self._dsn, **pool_kwargs)
+                effective_mode = "disable"
+            elif "sslmode=require" in self._dsn or "sslmode=verify" in self._dsn:
+                effective_mode = "require"
+            elif "sslmode=prefer" in self._dsn:
+                effective_mode = "prefer"
+            else:
+                effective_mode = self._ssl_mode
+
+            self._pool = await self._create_pool(effective_mode)
         return self._pool
 
+    async def _create_pool(self, ssl_mode: str) -> Any:
+        """Create the connection pool with the given SSL mode."""
+        import ssl as _ssl
+
+        pool_kwargs: dict[str, Any] = {
+            "min_size": 2,
+            "max_size": 10,
+            "command_timeout": self._command_timeout,
+        }
+
+        if ssl_mode == "disable":
+            # No SSL
+            pass
+        elif ssl_mode in ("require", "verify-full", "verify-ca"):
+            ssl_context = _ssl.create_default_context()
+            if not self._ssl_verify:
+                ssl_context.check_hostname = False
+                ssl_context.verify_mode = _ssl.CERT_NONE
+            pool_kwargs["ssl"] = ssl_context
+        elif ssl_mode == "prefer":
+            # Try SSL first, fall back to plaintext on rejection
+            ssl_context = _ssl.create_default_context()
+            ssl_context.check_hostname = False
+            ssl_context.verify_mode = _ssl.CERT_NONE
+            pool_kwargs["ssl"] = ssl_context
+            try:
+                return await asyncpg.create_pool(self._dsn, **pool_kwargs)
+            except Exception:
+                # SSL rejected; retry without
+                pool_kwargs.pop("ssl", None)
+
+        return await asyncpg.create_pool(self._dsn, **pool_kwargs)
+
     async def initialize(self) -> None:
         """Create schema, tables, and indexes."""
         pool = await self._get_pool()

tests/test_v1_features.py

@@ -398,6 +398,50 @@ def test_ssl_configurable(self) -> None:
         assert config.postgres_ssl_verify is True
 
 
+class TestPostgresBackendSSL:
+    """Test PostgresBackend SSL mode handling (sslmode=prefer by default)."""
+
+    def test_default_ssl_mode_is_prefer(self) -> None:
+        """PostgresBackend defaults to ssl='prefer' (try SSL, fall back)."""
+        from qp_vault.storage.postgres import HAS_ASYNCPG, PostgresBackend
+        if not HAS_ASYNCPG:
+            pytest.skip("asyncpg not installed")
+        backend = PostgresBackend("postgresql://localhost/test")
+        assert backend._ssl_mode == "prefer"
+
+    def test_ssl_true_normalizes_to_prefer(self) -> None:
+        """ssl=True normalizes to 'prefer' for backward compat."""
+        from qp_vault.storage.postgres import HAS_ASYNCPG, PostgresBackend
+        if not HAS_ASYNCPG:
+            pytest.skip("asyncpg not installed")
+        backend = PostgresBackend("postgresql://localhost/test", ssl=True)
+        assert backend._ssl_mode == "prefer"
+
+    def test_ssl_false_normalizes_to_disable(self) -> None:
+        """ssl=False normalizes to 'disable'."""
+        from qp_vault.storage.postgres import HAS_ASYNCPG, PostgresBackend
+        if not HAS_ASYNCPG:
+            pytest.skip("asyncpg not installed")
+        backend = PostgresBackend("postgresql://localhost/test", ssl=False)
+        assert backend._ssl_mode == "disable"
+
+    def test_ssl_require_string(self) -> None:
+        """ssl='require' is accepted as-is."""
+        from qp_vault.storage.postgres import HAS_ASYNCPG, PostgresBackend
+        if not HAS_ASYNCPG:
+            pytest.skip("asyncpg not installed")
+        backend = PostgresBackend("postgresql://localhost/test", ssl="require")
+        assert backend._ssl_mode == "require"
+
+    def test_ssl_disable_string(self) -> None:
+        """ssl='disable' is accepted as-is."""
+        from qp_vault.storage.postgres import HAS_ASYNCPG, PostgresBackend
+        if not HAS_ASYNCPG:
+            pytest.skip("asyncpg not installed")
+        backend = PostgresBackend("postgresql://localhost/test", ssl="disable")
+        assert backend._ssl_mode == "disable"
+
+
 # =============================================================================
 # FIPS KAT
 # =============================================================================