Adjust for feedback from PR#18999

.github/workflows/tests.yml

@@ -689,6 +689,9 @@ jobs:
           - arrangement: workers
             database: Postgres
 
+          - arrangement: monolith
+            database: Psycopg
+
           - arrangement: workers
             database: Psycopg
 

pyproject.toml

@@ -124,7 +124,11 @@ postgres = [
     "psycopg2cffi>=2.8;platform_python_implementation == 'PyPy'",
     "psycopg2cffi-compat==1.1;platform_python_implementation == 'PyPy'",
 ]
-psycopg = ["psycopg>=3.1"]
+# v3.2.8 was selected here as minimum to support the libpq5 shipped with debian
+# bookworm. This libpq5 includes support for postgres 18 and psycopg will fail to build
+# below this selected version.
+# See: https://github.com/psycopg/psycopg/pull/1084
+psycopg = ["psycopg[c]>=3.2.8"]
 saml2 = [
     "pysaml2>=4.5.0",
 
@@ -179,7 +183,7 @@ all = [
     "psycopg2cffi>=2.8;platform_python_implementation == 'PyPy'",
     "psycopg2cffi-compat==1.1;platform_python_implementation == 'PyPy'",
     # experimental psycopg for postgres
-    "psycopg>=3.1",
+    "psycopg[c]>=3.2.8",
     # saml2
     "pysaml2>=4.5.0",
     # oidc and jwt

scripts-dev/complement.sh

@@ -210,7 +210,7 @@ main() {
       echo_if_github "::endgroup::"
 
     fi
-  
+
     echo "Docker images built."
   else
     echo "Skipping Docker image build as requested."
@@ -271,8 +271,12 @@ main() {
     export PASS_SYNAPSE_WORKER_TYPES="$WORKER_TYPES"
 
     # Workers can only use Postgres as a database.
-    export PASS_SYNAPSE_COMPLEMENT_DATABASE=postgres
-
+    # A handy pattern for lower-casing all letters in a variable, `${variable,,}`
+    if [[ "${POSTGRES,,}" = "psycopg" ]]; then
+      export PASS_SYNAPSE_COMPLEMENT_DATABASE=psycopg
+    else
+      export PASS_SYNAPSE_COMPLEMENT_DATABASE=postgres
+    fi
     # And provide some more configuration to complement.
 
     # It can take quite a while to spin up a worker-mode Synapse for the first
@@ -281,7 +285,8 @@ main() {
     export COMPLEMENT_SPAWN_HS_TIMEOUT_SECS=120
   else
     export PASS_SYNAPSE_COMPLEMENT_USE_WORKERS=
-    if [[ "$POSTGRES" = "psycopg" ]]; then
+    # A handy pattern for lower-casing all letters in a variable, `${variable,,}`
+    if [[ "${POSTGRES,,}" = "psycopg" ]]; then
       export PASS_SYNAPSE_COMPLEMENT_DATABASE=psycopg
     elif [[ -n "$POSTGRES" ]]; then
       export PASS_SYNAPSE_COMPLEMENT_DATABASE=postgres
@@ -319,7 +324,7 @@ main() {
     echo "Skipping Complement run as requested."
     return 0
   fi
-  
+
   # Run the tests!
   echo "Running Complement with ${test_args[@]} $@ ${test_packages[@]}"
   cd "$COMPLEMENT_DIR"

synapse/storage/engines/postgres.py

@@ -44,6 +44,13 @@ class PostgresEngine(
     BaseDatabaseEngine[ConnectionType, CursorType, IsolationLevelType],
     metaclass=abc.ABCMeta,
 ):
+    """
+    An Abstract Base Class for use by Postgres connection libraries.
+    Currently supported:
+    * Psycopg2 -> `Psycopg2Engine`
+    * Psycopg -> `PsycopgEngine`
+    """
+
     isolation_level_map: Mapping[IsolationLevel, IsolationLevelType]
     default_isolation_level: IsolationLevelType
 

synapse/storage/engines/psycopg.py

@@ -33,6 +33,14 @@ class PsycopgEngine(
         psycopg.Connection[tuple], psycopg.Cursor[tuple], psycopg.IsolationLevel  # type: ignore[type-var]
     ]
 ):
+    """
+    The class that defines how Synapse will interact with Postgres using the psycopg
+    version 3+ module.
+
+    NOTE: While psycopg does allow for return types other than tuples, for now that is
+        forced in order to match with existing psycopg2 behavior.
+    """
+
     def __init__(self, database_config: Mapping[str, Any]):
         super().__init__(psycopg, database_config)  # type: ignore[arg-type]
         # psycopg2.extensions.register_type(psycopg2.extensions.UNICODE)

synapse/storage/engines/psycopg2.py

@@ -26,6 +26,12 @@
 class Psycopg2Engine(
     PostgresEngine[psycopg2.extensions.connection, psycopg2.extensions.cursor, int]
 ):
+    """
+    The class that defines how Synapse will interact with Postgres using the psycopg
+    version 2.x module.
+
+    """
+
     def __init__(self, database_config: Mapping[str, Any]):
         super().__init__(psycopg2, database_config)
         psycopg2.extensions.register_type(psycopg2.extensions.UNICODE)