feat!: switch PostgreSQL driver from psycopg2 to psycopg 3

CHANGELOG.md

@@ -1,9 +1,13 @@
 # Changelog
 
-## v8.0.0 (unreleased)
+## v8.0.0
 
 ### BREAKING CHANGE
 - Raise minimum supported Python version to 3.14. Wiremind decommissions Python 3.13.
+- Replace `psycopg2` with psycopg 3 (`psycopg[binary]`). SQLAlchemy 2.1+ uses psycopg 3 for
+  `postgresql://` by default; with SQLAlchemy 2.0, set `dialect: postgresql+psycopg`. Alembic
+  migrations that import `psycopg2` must move to `psycopg`, or install `psycopg2` and set
+  `dialect: postgresql+psycopg2`.
 
 ## v7.0.2 (2026-10-05)
 

docs/multi-database.md

@@ -49,7 +49,7 @@ databases:
 - `alembic_config_file_path`: Alembic configuration file name
 
 **Database connection components (all required):**
-- `dialect`: Database dialect (e.g., postgresql, mysql, sqlite)
+- `dialect`: Database dialect (e.g., postgresql, mysql, sqlite). With SQLAlchemy 2.1+, `postgresql` uses the psycopg 3 driver; with SQLAlchemy 2.0, set `postgresql+psycopg`. Set an explicit driver such as `postgresql+psycopg2` to override it.
 - `user`: Database username
 - `password`: Database password
 - `host`: Database host

pyproject.toml

@@ -16,7 +16,7 @@ classifiers = [
 dependencies = [
   "alembic",
   "kubernetes",
-  "psycopg2",
+  "psycopg[binary]",
   "pydantic>=2.0.0",
   "PyYAML",
 ]

requirements.txt

@@ -26,8 +26,10 @@ markupsafe==3.0.3
     # via mako
 oauthlib==3.3.1
     # via requests-oauthlib
-psycopg2==2.9.10
+psycopg==3.3.6
     # via chartreuse (pyproject.toml)
+psycopg-binary==3.3.6
+    # via psycopg
 pyasn1==0.6.1
     # via
     #   pyasn1-modules
@@ -56,7 +58,7 @@ six==1.17.0
     # via
     #   kubernetes
     #   python-dateutil
-sqlalchemy==2.0.43
+sqlalchemy==2.1.4
     # via alembic
 typing-extensions==4.15.0
     # via

src/chartreuse/config_loader.py

@@ -40,7 +40,8 @@ def url(self) -> str:
     def validate_dialect(cls, v: str) -> str:
         """Validate database dialect."""
         supported_dialects = ["postgresql", "mysql", "sqlite", "oracle", "mssql", "clickhouse"]
-        if v.lower() not in supported_dialects:
+        # Ignore the driver part, e.g. "postgresql+psycopg".
+        if v.lower().split("+")[0] not in supported_dialects:
             logger.warning("Dialect '%s' might not be supported. Supported dialects: %s", v, supported_dialects)
         return v