feat: add Alembic migration scripts for DB schema changes (closes imDarshanGK#596)

Author: lokeshkumar69

.github/workflows/migration-tests.yml

@@ -0,0 +1,35 @@
+name: Migration Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  migration-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          pip install alembic sqlalchemy
+
+      - name: Run upgrade (head)
+        working-directory: backend
+        run: alembic upgrade head
+
+      - name: Run downgrade (base)
+        working-directory: backend
+        run: alembic downgrade base
+
+      - name: Run upgrade again (verify roundtrip)
+        working-directory: backend
+        run: alembic upgrade head

backend/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = migrations
+prepend_sys_path = .
+sqlalchemy.url = sqlite:///./qyverix.db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/app/db/__init__.py

@@ -0,0 +1 @@
+

backend/app/db/database.py

@@ -0,0 +1,19 @@
+import os
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+
+DATABASE_URL: str = os.getenv("DATABASE_URL", "sqlite:///./qyverix.db")
+
+connect_args = {"check_same_thread": False} if DATABASE_URL.startswith("sqlite") else {}
+
+engine = create_engine(DATABASE_URL, connect_args=connect_args, echo=False)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

backend/app/db/models.py

@@ -0,0 +1,50 @@
+from datetime import datetime, timezone
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Integer, String, Text, JSON
+from sqlalchemy.orm import DeclarativeBase, relationship
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id               = Column(Integer, primary_key=True, index=True)
+    email            = Column(String(255), unique=True, nullable=False, index=True)
+    username         = Column(String(100), unique=True, nullable=False, index=True)
+    hashed_password  = Column(String(255), nullable=False)
+    is_active        = Column(Boolean, default=True, nullable=False)
+    created_at       = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+    updated_at       = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    analyses    = relationship("Analysis",   back_populates="user", cascade="all, delete-orphan")
+    share_links = relationship("ShareLink",  back_populates="user", cascade="all, delete-orphan")
+
+
+class ShareLink(Base):
+    __tablename__ = "share_links"
+
+    id         = Column(Integer, primary_key=True, index=True)
+    short_id   = Column(String(16), unique=True, nullable=False, index=True)
+    code       = Column(Text, nullable=False)
+    result     = Column(JSON, nullable=False)
+    user_id    = Column(Integer, ForeignKey("users.id", ondelete="SET NULL"), nullable=True, index=True)
+    created_at = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+
+    user = relationship("User", back_populates="share_links")
+
+
+class Analysis(Base):
+    __tablename__ = "analyses"
+
+    id           = Column(Integer, primary_key=True, index=True)
+    user_id      = Column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    language     = Column(String(50), nullable=True)
+    code_snippet = Column(Text, nullable=False)
+    result       = Column(JSON, nullable=False)
+    provider     = Column(String(50), nullable=False, default="rule-based")
+    created_at   = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+
+    user = relationship("User", back_populates="analyses")

backend/migrations/MIGRATIONS.md

@@ -0,0 +1,39 @@
+# Database Migrations
+
+This project uses **Alembic** for database schema migrations.
+
+## Setup
+
+```bash
+cd backend
+pip install alembic sqlalchemy
+```
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Apply all migrations | `alembic upgrade head` |
+| Rollback one step | `alembic downgrade -1` |
+| Rollback everything | `alembic downgrade base` |
+| Create new migration | `alembic revision -m "your message"` |
+| Check current version | `alembic current` |
+| View history | `alembic history` |
+
+## Environment Variable
+
+```bash
+# SQLite (default, local dev)
+DATABASE_URL=sqlite:///./qyverix.db
+
+# PostgreSQL (production)
+DATABASE_URL=postgresql+psycopg2://user:pass@host/dbname
+```
+
+## Migration Files
+
+| File | Description |
+|------|-------------|
+| `0001_initial_schema.py` | Creates users, share_links, analyses tables |
+| `0002_add_user_profile_fields.py` | Adds full_name, bio, avatar_url, last_login_at to users |
+| `0003_add_analysis_token_count.py` | Adds token_count, is_public to analyses; view_count to share_links |

backend/migrations/env.py

@@ -0,0 +1,54 @@
+import os
+import sys
+from logging.config import fileConfig
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from app.db.models import Base  # noqa: F401
+
+config = context.config
+
+database_url = os.getenv("DATABASE_URL", "sqlite:///./qyverix.db")
+config.set_main_option("sqlalchemy.url", database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+        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,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/migrations/versions/0001_initial_schema.py

@@ -0,0 +1,65 @@
+"""Initial schema: users, share_links, analyses
+
+Revision ID: 0001
+Revises: 
+Create Date: 2025-06-01 00:00:00.000000
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0001"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "users",
+        sa.Column("id",              sa.Integer(),     primary_key=True),
+        sa.Column("email",           sa.String(255),   nullable=False),
+        sa.Column("username",        sa.String(100),   nullable=False),
+        sa.Column("hashed_password", sa.String(255),   nullable=False),
+        sa.Column("is_active",       sa.Boolean(),     nullable=False, server_default=sa.text("1")),
+        sa.Column("created_at",      sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+        sa.Column("updated_at",      sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+    )
+    op.create_index("ix_users_email",    "users", ["email"],    unique=True)
+    op.create_index("ix_users_username", "users", ["username"], unique=True)
+    op.create_index("ix_users_id",       "users", ["id"])
+
+    op.create_table(
+        "share_links",
+        sa.Column("id",         sa.Integer(),               primary_key=True),
+        sa.Column("short_id",   sa.String(16),              nullable=False),
+        sa.Column("code",       sa.Text(),                  nullable=False),
+        sa.Column("result",     sa.JSON(),                  nullable=False),
+        sa.Column("user_id",    sa.Integer(),               nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="SET NULL"),
+    )
+    op.create_index("ix_share_links_short_id", "share_links", ["short_id"], unique=True)
+    op.create_index("ix_share_links_user_id",  "share_links", ["user_id"])
+    op.create_index("ix_share_links_id",       "share_links", ["id"])
+
+    op.create_table(
+        "analyses",
+        sa.Column("id",           sa.Integer(),  primary_key=True),
+        sa.Column("user_id",      sa.Integer(),  nullable=False),
+        sa.Column("language",     sa.String(50), nullable=True),
+        sa.Column("code_snippet", sa.Text(),     nullable=False),
+        sa.Column("result",       sa.JSON(),     nullable=False),
+        sa.Column("provider",     sa.String(50), nullable=False, server_default="rule-based"),
+        sa.Column("created_at",   sa.DateTime(timezone=True), nullable=False, server_default=sa.text("CURRENT_TIMESTAMP")),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+    )
+    op.create_index("ix_analyses_user_id", "analyses", ["user_id"])
+    op.create_index("ix_analyses_id",      "analyses", ["id"])
+
+
+def downgrade() -> None:
+    op.drop_table("analyses")
+    op.drop_table("share_links")
+    op.drop_table("users")

backend/migrations/versions/0002_add_user_profile_fields.py

@@ -0,0 +1,28 @@
+"""Add profile fields to users table
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2025-06-02 00:00:00.000000
+"""
+from typing import Sequence, Union
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0002"
+down_revision: Union[str, None] = "0001"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("full_name",     sa.String(200), nullable=True))
+    op.add_column("users", sa.Column("bio",           sa.Text(),      nullable=True))
+    op.add_column("users", sa.Column("avatar_url",    sa.String(500), nullable=True))
+    op.add_column("users", sa.Column("last_login_at", sa.DateTime(timezone=True), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("users", "last_login_at")
+    op.drop_column("users", "avatar_url")
+    op.drop_column("users", "bio")
+    op.drop_column("users", "full_name")