Persistent storage: DATABASE_URL (Postgres/Supabase) support + deploy steps

.env.example

@@ -56,5 +56,9 @@
 # password resets, failed-run requeue, verification queue, usage stats).
 # ADMIN_EMAILS=devaanand@umass.edu,matari@umass.edu
 
-# ---- Phase 2 (not read yet; reserved names) ----
-# DATABASE_URL=postgresql://...
+# ---- Database (persistent storage) ----
+# Unset = SQLite under CCR_DATA_DIR (local dev; wiped on ephemeral hosts like HF Spaces).
+# Set to a Postgres URL for durable storage. Supabase (free tier) recommended -
+# use the "Session pooler" connection string from Project Settings > Database,
+# and put your DB password in it. Accounts and all data then survive restarts.
+# DATABASE_URL=postgresql://postgres.PROJECTREF:PASSWORD@aws-0-REGION.pooler.supabase.com:5432/postgres

DEPLOY.md

@@ -54,3 +54,19 @@ the password when prompted (or a credential helper).
   on next sign-in automatically; password accounts must re-register. Fine for
   feedback; a persistent volume or Postgres arrives with the launch decision.
 - The Space sleeps after ~48 h idle; first visit wakes it (~1 min).
+
+## Persistent storage (make accounts/data survive restarts)
+
+HF Spaces free disk is ephemeral - SQLite is wiped on every rebuild. Point the
+app at your Supabase Postgres (free, already used for Google auth):
+
+1. Supabase dashboard > Project Settings > Database > Connection string >
+   "Session pooler". Copy the URI and put your DB password into it.
+2. Add it as a Space secret named `DATABASE_URL`.
+3. Restart the Space. First boot creates the tables in Postgres; data now
+   persists across restarts and redeploys.
+
+For durable uploaded FILES too (not just the database), also set the
+`CCR_STORAGE=s3` R2 secrets (see .env.example). Without that, the database
+rows survive but a signed-in user's uploaded corpus file can still vanish on
+restart (results CSVs are regenerable by re-running).

backend/app/db.py

@@ -1,9 +1,16 @@
-"""Database setup - SQLite via SQLAlchemy.
+"""Database setup - SQLite (local dev) or PostgreSQL (deployments).
 
-SQLite is a deliberate choice for this deployment size (single-node, few
-concurrent writers). The models use no SQLite-specific features, so moving
-to PostgreSQL when multi-user concurrency arrives is a connection-string
-change plus a migration, not a rewrite.
+Backend chosen by DATABASE_URL:
+  * unset            -> SQLite file under CCR_DATA_DIR (local dev; zero setup),
+  * postgres URL     -> PostgreSQL (Supabase free tier recommended: persistent,
+                        backed up, and already the auth provider - one vendor).
+
+The models use no backend-specific features, so this is a connection-string
+change, not a rewrite. On the ephemeral-disk hosts (HF Spaces free), SQLite is
+wiped on every restart; Postgres is what makes accounts and data survive.
+
+DATA_DIR still holds corpora/results/cache files locally; for durable FILE
+storage on ephemeral hosts, additionally set CCR_STORAGE=s3 (storage.py).
 """
 
 import os
@@ -12,8 +19,6 @@ from pathlib import Path
 from sqlalchemy import create_engine, event
 from sqlalchemy.orm import DeclarativeBase, sessionmaker
 
-# CCR_DATA_DIR overrides where the DB, corpora, and results live
-# (used by tests to keep runs isolated; useful for deployments too).
 DATA_DIR = Path(
     os.environ.get("CCR_DATA_DIR", Path(__file__).resolve().parent.parent / "data")
 )
@@ -21,23 +26,44 @@ DATA_DIR.mkdir(parents=True, exist_ok=True)
 (DATA_DIR / "corpora").mkdir(exist_ok=True)
 (DATA_DIR / "results").mkdir(exist_ok=True)
 
-DB_PATH = DATA_DIR / "ccr.db"
-
-engine = create_engine(
-    f"sqlite:///{DB_PATH}",
-    connect_args={"check_same_thread": False},  # FastAPI threadpool access
-)
-
 
-@event.listens_for(engine, "connect")
-def _sqlite_pragmas(dbapi_conn, _record):
-    """WAL lets the API read while the job worker writes; busy_timeout
-    absorbs brief lock contention instead of raising immediately."""
-    cur = dbapi_conn.cursor()
-    cur.execute("PRAGMA journal_mode=WAL")
-    cur.execute("PRAGMA busy_timeout=5000")
-    cur.execute("PRAGMA synchronous=NORMAL")
-    cur.close()
+def _normalize_pg_url(url: str) -> str:
+    """Force the psycopg (v3) driver; accept the bare postgres:// URL that
+    dashboards (Supabase) hand out."""
+    if url.startswith("postgres://"):
+        url = "postgresql://" + url[len("postgres://"):]
+    if url.startswith("postgresql://"):
+        url = "postgresql+psycopg://" + url[len("postgresql://"):]
+    return url
+
+
+_DATABASE_URL = os.environ.get("DATABASE_URL", "").strip()
+IS_POSTGRES = _DATABASE_URL.startswith(("postgres://", "postgresql://"))
+
+if IS_POSTGRES:
+    engine = create_engine(
+        _normalize_pg_url(_DATABASE_URL),
+        pool_pre_ping=True,   # survive Supabase idle-connection drops
+        pool_recycle=1800,
+        pool_size=5,
+        max_overflow=5,
+    )
+else:
+    DB_PATH = DATA_DIR / "ccr.db"
+    engine = create_engine(
+        f"sqlite:///{DB_PATH}",
+        connect_args={"check_same_thread": False},  # FastAPI threadpool access
+    )
+
+    @event.listens_for(engine, "connect")
+    def _sqlite_pragmas(dbapi_conn, _record):
+        """WAL lets the API read while the job worker writes; busy_timeout
+        absorbs brief lock contention instead of raising immediately."""
+        cur = dbapi_conn.cursor()
+        cur.execute("PRAGMA journal_mode=WAL")
+        cur.execute("PRAGMA busy_timeout=5000")
+        cur.execute("PRAGMA synchronous=NORMAL")
+        cur.close()
 
 
 SessionLocal = sessionmaker(bind=engine, autoflush=False, expire_on_commit=False)
@@ -56,8 +82,10 @@ def get_db():
         db.close()
 
 
-def _sqlite_literal(value) -> str:
+def _default_literal(value, dialect_name: str) -> str:
     if isinstance(value, bool):
+        if dialect_name == "postgresql":
+            return "TRUE" if value else "FALSE"
         return "1" if value else "0"
     if isinstance(value, (int, float)):
         return str(value)
@@ -65,20 +93,22 @@ def _sqlite_literal(value) -> str:
 
 
 def auto_migrate_sqlite(target_engine, metadata) -> list[str]:
-    """Add ORM columns missing from existing SQLite tables (additive only).
-
-    create_all() creates missing tables but never alters existing ones, so a
-    dev DB from last week 500s on this week's new column. This closes that gap
-    for the additive changes we make; anything non-additive (renames, drops,
-    type changes) waits for Alembic, which replaces this in Phase 2 alongside
-    Postgres. Columns with scalar defaults get that default; callable defaults
-    (uuid/now) are added nullable and filled by the ORM on new rows.
+    """Add ORM columns missing from existing tables (additive only).
+
+    Named for history; runs on both backends. create_all() creates missing
+    tables but never alters existing ones, so a DB from last week 500s on this
+    week's new column. This closes that gap for additive changes; anything
+    non-additive (renames, drops, type changes) waits for Alembic. Columns with
+    scalar defaults get that default; callable defaults (uuid/now) are added
+    nullable and filled by the ORM on new rows. A brand-new Postgres database
+    needs none of this (create_all already made every current column).
     """
     import logging
 
     from sqlalchemy import inspect, text
 
     added: list[str] = []
+    dialect = target_engine.dialect.name
     inspector = inspect(target_engine)
     with target_engine.begin() as conn:
         for table in metadata.sorted_tables:
@@ -92,7 +122,7 @@ def auto_migrate_sqlite(target_engine, metadata) -> list[str]:
                 ddl = f'ALTER TABLE {table.name} ADD COLUMN "{column.name}" {col_type}'
                 default = getattr(column.default, "arg", None)
                 if default is not None and not callable(default):
-                    ddl += f" DEFAULT {_sqlite_literal(default)}"
+                    ddl += f" DEFAULT {_default_literal(default, dialect)}"
                 conn.execute(text(ddl))
                 added.append(f"{table.name}.{column.name}")
     if added:

backend/requirements.txt

@@ -10,3 +10,4 @@ sentence-transformers>=2.6
 pyyaml>=6.0
 langdetect>=1.0.9
 boto3>=1.34  # used only when CCR_STORAGE=s3 (Cloudflare R2 / any S3-compatible store)
+psycopg[binary]>=3.1  # used only when DATABASE_URL is a Postgres URL (Supabase)