Implement database migration

.gitignore

@@ -381,3 +381,6 @@ data
 *.db
 package-lock.json
 dist-electron
+backend/migrations/**
+!backend/migrations/env.py
+!backend/migrations/script.py.mako

backend/app.py

@@ -1,5 +1,7 @@
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from migration import run_auto_migration
+from db import engine
 
 from routes import account, messaging, profile, push
 
@@ -20,3 +22,12 @@ app.include_router(account.router)
 app.include_router(messaging.router)
 app.include_router(profile.router)
 app.include_router(push.router, prefix="/push")
+
+
+@app.on_event("startup")
+def _auto_migrate_on_startup():
+    try:
+        run_auto_migration(engine)
+    except Exception:
+        # Keep startup resilient; errors should be visible in server logs
+        pass

backend/migration.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+from traceback import format_exc
+import hashlib
+
+from sqlalchemy.engine import Engine
+
+from alembic import command
+from alembic.config import Config
+
+from models import Base
+from constants import DATABASE_URL
+
+
+MIGRATIONS_DIR = Path(__file__).resolve().parent / "migrations"
+LOCK_FILE = MIGRATIONS_DIR / ".autogen.lock"
+SCHEMA_HASH_FILE = MIGRATIONS_DIR / ".schema.hash"
+
+
+def _ensure_alembic_layout() -> None:
+    """Create a minimal Alembic environment if missing."""
+    versions = MIGRATIONS_DIR / "versions"
+    versions.mkdir(parents=True, exist_ok=True)
+
+
+def _alembic_config() -> Config:
+    cfg = Config()
+    cfg.set_main_option("script_location", str(MIGRATIONS_DIR))
+    cfg.set_main_option("sqlalchemy.url", DATABASE_URL)
+    # Provide a minimal ini section so env.py can read config_ini_section
+    cfg.config_file_name = "alembic.ini"
+    cfg.set_section_option("alembic", "sqlalchemy.url", DATABASE_URL)
+    return cfg
+
+
+def _model_schema_fingerprint() -> str:
+    """Compute a deterministic fingerprint of the current SQLAlchemy model schema."""
+    parts: list[str] = []
+    md = Base.metadata
+    for table in sorted(md.tables.values(), key=lambda t: t.name):
+        parts.append(f"T:{table.name}")
+        for col in sorted(table.columns, key=lambda c: c.name):
+            col_type = str(col.type)
+            parts.append(f"C:{col.name}:{col_type}:N{int(bool(col.nullable))}")
+    digest = hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()
+    return digest
+
+
+def run_auto_migration(engine: Engine) -> None:
+    """Use Alembic to autogenerate and apply migrations automatically on startup."""
+    # Ensure env present
+    _ensure_alembic_layout()
+    cfg = _alembic_config()
+
+    try:
+        # Upgrade existing migrations (if any) first
+        command.upgrade(cfg, "head")
+    except Exception:
+        print("[alembic] upgrade to head failed:\n" + format_exc())
+
+    # Always attempt autogenerate only when model schema fingerprint changed
+    try:
+        # Avoid concurrent autogenerate on dev server reloads
+        try:
+            LOCK_FILE.parent.mkdir(parents=True, exist_ok=True)
+            fd = os.open(str(LOCK_FILE), os.O_CREAT | os.O_EXCL | os.O_RDWR)
+            os.close(fd)
+            have_lock = True
+        except FileExistsError:
+            have_lock = False
+
+        if have_lock:
+            try:
+                new_hash = _model_schema_fingerprint()
+                old_hash = SCHEMA_HASH_FILE.read_text(encoding="utf-8").strip() if SCHEMA_HASH_FILE.exists() else ""
+                if new_hash != old_hash:
+                    command.revision(cfg, message="auto", autogenerate=True)
+                    command.upgrade(cfg, "head")
+                    # Update stored fingerprint
+                    SCHEMA_HASH_FILE.write_text(new_hash, encoding="utf-8")
+            finally:
+                try:
+                    LOCK_FILE.unlink(missing_ok=True)
+                except Exception:
+                    pass
+    except Exception:
+        print("[alembic] autogenerate failed:\n" + format_exc())
+
+

backend/migrations/env.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+from sqlalchemy import engine_from_config, pool
+from alembic import context
+from models import Base
+
+config = context.config
+target_metadata = Base.metadata
+
+
+def _skip_empty_autogenerate(ctx, rev, directives):
+    # Avoid creating empty migrations when there are no schema changes
+    if getattr(config, "cmd_opts", None) and getattr(config.cmd_opts, "autogenerate", False):
+        if directives:
+            script = directives[0]
+            if hasattr(script, "upgrade_ops") and script.upgrade_ops.is_empty():
+                directives[:] = []
+
+def run_migrations_offline():
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url, target_metadata=target_metadata, literal_binds=True, dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,
+        process_revision_directives=_skip_empty_autogenerate
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+def run_migrations_online():
+    connectable = engine_from_config(config.get_section(config.config_ini_section) or {}, prefix="sqlalchemy.", poolclass=pool.NullPool)
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            render_as_batch=True,
+            process_revision_directives=_skip_empty_autogenerate
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/migrations/script.py.mako

@@ -0,0 +1,23 @@
+
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = '${up_revision}'
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+def upgrade():
+    pass
+
+def downgrade():
+    pass

backend/requirements.txt

@@ -8,3 +8,4 @@ Pillow>=10.0.0
 python-multipart>=0.0.6
 pywebpush>=1.14.0
 cryptography>=41.0.0
+alembic>=1.13.2

package.json

@@ -11,7 +11,7 @@
         "backend:run": "cd backend && dotenv -e ../deployment/.env -- ../.venv/bin/fastapi dev --port 8300 main.py",
         "backend:dependencies": "python3 -m venv .venv && ./.venv/bin/pip3 install -r backend/requirements.txt",
         "backend:reinstall": "rm -rf .venv && npm run backend:dependencies",
-        "backend:clean": "rm -rf backend/data",
+        "backend:clean": "rm -rf backend/data && rm -rf backend/migrations",
         "frontend:dev": "vite frontend",
         "frontend:typecheck": "tsc --project frontend",
         "frontend:build": "npm run frontend:typecheck && vite build frontend",