h

database/db.py

@@ -1,14 +1,24 @@
 """
 database/db.py — Async SQLAlchemy engine and session factory.
 
-KEY FIX — Supabase uses PgBouncer as a connection pooler (Transaction mode).
-PgBouncer shares connections between clients, which conflicts with asyncpg's
-prepared-statement cache. The fix is:
-
-    "statement_cache_size": 0
-
-This tells asyncpg NOT to cache prepared statements, which prevents the error:
-    "prepared statement '__asyncpg_stmt_X__' already exists"
+ROOT CAUSE OF THE BUG:
+  Supabase uses PgBouncer in **Transaction Pooler** mode.
+  PgBouncer reuses the same underlying DB connection for many different
+  clients. asyncpg caches "prepared statements" per-connection. When
+  PgBouncer hands the same connection to another client, asyncpg tries
+  to create the same prepared statement again and PostgreSQL raises:
+
+      DuplicatePreparedStatementError:
+      prepared statement "__asyncpg_stmt_2__" already exists
+
+THE FIX — use NullPool:
+  SQLAlchemy's NullPool opens a brand-new raw connection for every
+  session and closes it immediately when the session ends.
+  Because every connection is fresh, there is never a leftover prepared
+  statement to conflict with. PgBouncer handles the actual pooling on
+  its side, so SQLAlchemy doesn't need its own pool at all.
+
+  This is the officially recommended approach for Supabase + asyncpg.
 """
 
 from sqlalchemy.ext.asyncio import (
@@ -16,40 +26,36 @@ from sqlalchemy.ext.asyncio import (
     create_async_engine,
     async_sessionmaker,
 )
+from sqlalchemy.pool import NullPool          # ← THE KEY FIX
+
 from config import config
 from database.models import Base
 
 
 engine = create_async_engine(
     config.DATABASE_URL,
-    echo=False,
 
-    # ── Pool settings ────────────────────────────────────────
-    # Keep pool small — Supabase free tier has a connection limit.
-    pool_size=5,
-    max_overflow=10,
-    pool_pre_ping=True,       # Drop stale connections automatically
-    pool_recycle=300,         # Recycle connections every 5 minutes
+    # ── NullPool: no SQLAlchemy-level connection pooling ─────
+    # PgBouncer (Supabase) is the pool. SQLAlchemy should not
+    # add another caching layer on top of it.
+    poolclass=NullPool,
 
-    # ── asyncpg connect_args ─────────────────────────────────
+    # ── asyncpg connection arguments ─────────────────────────
     connect_args={
-        # CRITICAL: Disable prepared-statement cache.
-        # Required when using Supabase Transaction Pooler (PgBouncer).
-        # Without this you get:
-        #   "prepared statement '__asyncpg_stmt_X__' already exists"
-        "statement_cache_size": 0,
-
-        # SSL is mandatory for Supabase connections.
-        "ssl": "require",
+        "ssl"            : "require",   # Mandatory for Supabase
+        "timeout"        : 30,          # Connect timeout (seconds)
+        "command_timeout": 60,          # Query timeout (seconds)
 
-        # Timeout in seconds for establishing a new connection.
-        "timeout": 30,
-
-        # Timeout for individual queries.
-        "command_timeout": 60,
+        # Belt-and-suspenders: also disable the statement cache
+        # inside asyncpg itself (the NullPool already prevents
+        # the conflict, but this makes doubly sure).
+        "statement_cache_size": 0,
     },
+
+    echo=False,   # Set True temporarily to log all SQL for debugging
 )
 
+
 AsyncSessionFactory = async_sessionmaker(
     bind=engine,
     class_=AsyncSession,
@@ -58,14 +64,20 @@ AsyncSessionFactory = async_sessionmaker(
 )
 
 
-async def init_db():
-    """Create all database tables defined in models.py if they don't exist."""
+async def init_db() -> None:
+    """Create all tables defined in models.py if they don't exist yet."""
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
     print("✅ Database tables initialized.")
 
 
 async def get_session() -> AsyncSession:
-    """Async context manager for a DB session."""
+    """
+    Async context-manager that yields a DB session.
+
+    Usage:
+        async with AsyncSessionFactory() as session:
+            result = await session.execute(...)
+    """
     async with AsyncSessionFactory() as session:
         yield session