Support psycopg as a PostgreSQL driver

.ci/scripts/calculate_jobs.py

@@ -56,23 +56,38 @@ def set_output(key: str, value: str):
         for version in ("3.10", "3.11", "3.12", "3.13")
     )
 
+# Run with both psycopg2 and psycopg.
 trial_postgres_tests = [
     {
         "python-version": "3.9",
         "database": "postgres",
         "postgres-version": "13",
         "extras": "all",
-    }
+    },
+    {
+        "python-version": "3.9",
+        "database": "psycopg",
+        "postgres-version": "13",
+        "extras": "all",
+    },
 ]
 
 if not IS_PR:
-    trial_postgres_tests.append(
-        {
-            "python-version": "3.13",
-            "database": "postgres",
-            "postgres-version": "17",
-            "extras": "all",
-        }
+    trial_postgres_tests.extend(
+        [
+            {
+                "python-version": "3.13",
+                "database": "postgres",
+                "postgres-version": "17",
+                "extras": "all",
+            },
+            {
+                "python-version": "3.13",
+                "database": "psycopg",
+                "postgres-version": "17",
+                "extras": "all",
+            },
+        ]
     )
 
 trial_no_extra_tests = [

.github/workflows/tests.yml

@@ -428,7 +428,9 @@ jobs:
         run: until pg_isready -h localhost; do sleep 1; done
       - run: poetry run trial --jobs=6 tests
         env:
-          SYNAPSE_POSTGRES: ${{ matrix.job.database == 'postgres' || '' }}
+          # If matrix.job.database is 'psycopg' set SYNAPSE_POSTGRES to that string;
+          # otherwise if it is 'postgres' set it to true. Otherwise, empty.
+          SYNAPSE_POSTGRES: ${{ matrix.job.database == 'psycopg' && 'psycopg' || matrix.job.database == 'postgres' || '' }}
           SYNAPSE_POSTGRES_HOST: /var/run/postgresql
           SYNAPSE_POSTGRES_USER: postgres
           SYNAPSE_POSTGRES_PASSWORD: postgres
@@ -712,6 +714,9 @@ jobs:
           - arrangement: workers
             database: Postgres
 
+          - arrangement: workers
+            database: Psycopg
+
     steps:
       - name: Checkout synapse codebase
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
@@ -738,7 +743,7 @@ jobs:
           COMPLEMENT_DIR=`pwd`/complement synapse/scripts-dev/complement.sh -p 1 -json 2>&1 | synapse/.ci/scripts/gotestfmt
         shell: bash
         env:
-          POSTGRES: ${{ (matrix.database == 'Postgres') && 1 || '' }}
+          POSTGRES: ${{ (matrix.database == 'Postgres' || matrix.database == 'Psycopg') && matrix.database || '' }}
           WORKERS: ${{ (matrix.arrangement == 'workers') && 1 || '' }}
         name: Run Complement Tests
 

changelog.d/18999.feature

@@ -0,0 +1 @@
+Support using psycopg as the PostgreSQL driver. Contributed by @clokep and @realtyem.

docker/complement/conf/start_for_complement.sh

@@ -23,6 +23,18 @@ export SYNAPSE_REPORT_STATS=no
 case "$SYNAPSE_COMPLEMENT_DATABASE" in
   postgres)
     # Set postgres authentication details which will be placed in the homeserver config file
+    export POSTGRES_DRIVER=psycopg2
+    export POSTGRES_PASSWORD=somesecret
+    export POSTGRES_USER=postgres
+    export POSTGRES_HOST=localhost
+
+    # configure supervisord to start postgres
+    export START_POSTGRES=true
+    ;;
+
+  psycopg)
+    # Set postgres authentication details which will be placed in the homeserver config file
+    export POSTGRES_DRIVER=psycopg
     export POSTGRES_PASSWORD=somesecret
     export POSTGRES_USER=postgres
     export POSTGRES_HOST=localhost

docker/conf/homeserver.yaml

@@ -57,11 +57,11 @@ listeners:
 
 {% if POSTGRES_PASSWORD %}
 database:
-  name: "psycopg2"
+  name: "{{ POSTGRES_DRIVER or "psycopg2" }}"
   args:
     user: "{{ POSTGRES_USER or "synapse" }}"
     password: "{{ POSTGRES_PASSWORD }}"
-    database: "{{ POSTGRES_DB or "synapse" }}"
+    dbname: "{{ POSTGRES_DB or "synapse" }}"
 {% if not SYNAPSE_USE_UNIX_SOCKET %}
 {# Synapse will use a default unix socket for Postgres when host/port is not specified (behavior from `psycopg2`). #}
     host: "{{ POSTGRES_HOST or "db" }}"

docs/usage/configuration/config_documentation.md

@@ -1466,7 +1466,7 @@ For more information on using Synapse with Postgres, see [here](../../postgres.m
 
 This setting has the following sub-options:
 
-* `name` (string): This option specifies the database engine to use: either `sqlite3` (for SQLite) or `psycopg2` (for PostgreSQL). If no name is specified Synapse will default to SQLite. Defaults to `"sqlite3"`.
+* `name` (string): This option specifies the database engine to use: either `sqlite3` (for SQLite) or `psycopg2` (for PostgreSQL). `psycopg` references the experimental psycopg3 driver, which may be used as a drop in replacement  for `psycopg2`. If no name is specified Synapse will default to SQLite. Defaults to `"sqlite3"`.
 
 * `txn_limit` (integer): Gives the maximum number of transactions to run per connection before reconnecting. 0 means no limit. Defaults to `0`.