Ft/add alembic support (#78)

Improves #76

Author: Aditya0545

README.md

@@ -65,10 +65,16 @@ A web platform for hosting and participating in collaborative online competition
 
    d. Users can then click "Login with Wikimedia" on the login page
 
-7. **Initialize database**
+7. **Initialize database with Alembic migrations**
    ```bash
-   python init_db.py
+   # Apply all database migrations
+   alembic upgrade head
+   
+   # Or use the helper script
+   python scripts/migrate.py upgrade head
    ```
+   
+   **Note**: The app does not automatically run migrations on startup. You must run Alembic migrations manually before starting the application.
 
 8. **Run the application**
 
@@ -78,7 +84,7 @@ A web platform for hosting and participating in collaborative online competition
 
    Terminal 1 - Flask Backend:
    ```bash
-   python app.py
+   python main.py
    ```
 
    Terminal 2 - Vue.js Frontend:
@@ -98,7 +104,7 @@ A web platform for hosting and participating in collaborative online competition
    npm install  # Only needed first time
    npm run build
    cd ../backend
-   python app.py
+   python main.py
    ```
 
    Access at: `http://localhost:5000` (Flask serves built Vue.js files)
@@ -109,6 +115,8 @@ A web platform for hosting and participating in collaborative online competition
 
 **Quick Testing Option**: If you want to skip MySQL setup, edit `.env` and change `DATABASE_URL` to `sqlite:///wikicontest.db`
 
+**Database Migrations**: The application uses Alembic for database migrations. Always run `alembic upgrade head` before starting the app to ensure your database schema is up to date. The app does not automatically run migrations on startup.
+
 **Frontend Development**: For the best development experience, run the Vue.js dev server (`npm run dev` in `frontend/` directory) alongside Flask. The dev server proxies API requests to Flask automatically.
 
 ## 🔧 Configuration
@@ -146,8 +154,11 @@ The `.env.example` file contains all configuration options. Copy it to `.env` an
 ## 🧪 Testing
 
 ```bash
+# Make sure migrations are applied first
+alembic upgrade head
+
 # Test the application
-python app.py
+python main.py
 # Open http://localhost:5000 and test:
 # - User registration/login
 # - Contest creation
@@ -162,21 +173,30 @@ python app.py
    export DATABASE_URL=your-production-mysql-url
    ```
 
-2. **Run with production server**
+2. **Apply database migrations**
+   ```bash
+   alembic upgrade head
+   ```
+
+3. **Run with production server**
    ```bash
    pip install gunicorn
-   gunicorn -w 4 -b 0.0.0.0:5000 app:app
+   gunicorn -w 4 -b 0.0.0.0:5000 "app:app"
    ```
 
 ## Project Structure
 
 ```
 wikicontest/
 ├── backend/           # Flask application
-│   ├── app.py        # Main application
-│   ├── models/       # Database models
-│   ├── routes/        # API endpoints
-│   └── middleware/    # Authentication
+│   ├── main.py       # Application entry point
+│   ├── app/          # Application package
+│   │   ├── __init__.py  # Flask app factory
+│   │   ├── models/   # Database models
+│   │   ├── routes/   # API endpoints
+│   │   └── middleware/ # Authentication
+│   ├── alembic/      # Database migrations (Alembic)
+│   └── scripts/      # Utility scripts
 └── frontend/         # Vue.js frontend
     ├── src/          # Source files
     │   ├── views/    # Page components

backend/README.md

@@ -41,11 +41,6 @@ backend/
 │   ├── versions/               # Migration version files
 │   ├── script.py.mako         # Migration template
 │   └── README.md               # Alembic documentation
-├── migrations/                 # Custom migration scripts (one-time/data migrations)
-│   ├── README.md
-│   ├── add_article_metadata_to_submissions.py
-│   ├── add_expansion_bytes_to_submissions.py
-│   └── add_size_at_start_to_submissions.py
 ├── scripts/                     # Utility scripts
 │   ├── init_db.py               # Database initialization
 │   ├── backfill_article_info.py # Backfill article metadata
@@ -333,17 +328,6 @@ For detailed Alembic documentation, see:
 - [`docs/ALEMBIC_MODEL_COMPATIBILITY.md`](docs/ALEMBIC_MODEL_COMPATIBILITY.md) - Model compatibility guide
 - [`docs/ALEMBIC_SETUP_VERIFICATION.md`](docs/ALEMBIC_SETUP_VERIFICATION.md) - Setup verification checklist
 
-#### Legacy Migration Scripts
-
-The application also includes custom migration scripts in the `migrations/` directory for reference. These can be run manually if needed:
-
-```bash
-# Run a specific migration
-python migrations/add_article_metadata_to_submissions.py
-```
-
-**Note**: For new schema changes, use Alembic migrations instead of custom scripts.
-
 ### Utility Scripts
 
 Scripts in the `scripts/` directory:

backend/app/__init__.py

@@ -29,8 +29,7 @@
 from flask_jwt_extended.exceptions import JWTDecodeError, NoAuthorizationError
 from dotenv import load_dotenv
 import requests
-from sqlalchemy import text, inspect
-from sqlalchemy.exc import SQLAlchemyError, ProgrammingError, OperationalError
+from sqlalchemy.exc import SQLAlchemyError
 
 # Local imports
 from app.database import db
@@ -743,70 +742,14 @@ def internal_error(_error):
 # APPLICATION STARTUP
 # =============================================================================
 
-def migrate_database():
-    """
-    Run database migrations to add new columns if they don't exist.
-    This ensures the database schema matches the current model definitions.
-    """
-    try:
-        # Get table inspector to check existing columns
-        inspector = inspect(db.engine)
-        columns = [col['name'] for col in inspector.get_columns('submissions')]
-
-        # Check which columns need to be added
-        columns_to_add = []
-        if 'article_author' not in columns:
-            columns_to_add.append(('article_author', 'VARCHAR(200) NULL'))
-        if 'article_created_at' not in columns:
-            columns_to_add.append(('article_created_at', 'VARCHAR(50) NULL'))
-        if 'article_word_count' not in columns:
-            columns_to_add.append(('article_word_count', 'INT NULL'))
-        if 'article_page_id' not in columns:
-            columns_to_add.append(('article_page_id', 'VARCHAR(50) NULL'))
-
-        # Add missing columns
-        if columns_to_add:
-            print("📦 Running database migration: Adding article metadata columns...")
-            for col_name, col_type in columns_to_add:
-                try:
-                    db.session.execute(
-                        text(f"ALTER TABLE submissions ADD COLUMN {col_name} {col_type}")
-                    )
-                    print(f"  ✓ Added column: {col_name}")
-                except (ProgrammingError, OperationalError) as error:
-                    # Column might already exist or there's a SQL/database error
-                    print(f"  ⚠ Could not add column {col_name}: {error}")
-
-            db.session.commit()
-            print("✓ Database migration completed")
-        else:
-            print("✓ Database schema is up to date")
-
-    except (OperationalError, SQLAlchemyError) as error:
-        # If table doesn't exist yet, db.create_all() will handle it
-        # Or if there's a database connection/query error
-        print(f"⚠ Migration check skipped (table may not exist yet): {error}")
-        db.session.rollback()
-
 if __name__ == '__main__':
-    # Main application entry point.
-    # This section runs when the script is executed directly (not imported).
-    # It initializes the database tables and starts the Flask development server.
-
-    # Initialize database tables
-    # This creates all tables defined in the models if they don't exist
-    with app.app_context():
-        db.create_all()
-        print("✓ Database tables initialized successfully")
-
-        # Run migrations to add new columns to existing tables
-        migrate_database()
-
-    # Start the Flask development server
+    # This file can be run directly, but main.py is the recommended entry point.
+    # Database migrations are handled by Alembic - run 'alembic upgrade head' before starting.
     # Debug mode is enabled for development (disable in production)
     print("🚀 Starting WikiContest API server...")
     print("📡 Server will be available at: http://localhost:5000")
     print("🔧 Debug mode: ENABLED")
+    print("ℹ Note: Use Alembic for database migrations (alembic upgrade head)")
 
     app.run(
         debug=True,        # Enable debug mode for development

backend/docs/ALEMBIC_USAGE_GUIDE.md

@@ -353,17 +353,17 @@ If you have conflicts with existing migrations:
 
 10. **Use transactions** - Alembic wraps migrations in transactions by default, but be aware of database-specific limitations
 
-## Integration with Existing Migrations
+## Migration Strategy
 
-The project also has custom migration scripts in the `migrations/` directory. These can coexist with Alembic migrations:
+The project uses **Alembic exclusively** for all database migrations:
 
-- **Custom migrations** (`migrations/`): For one-time data migrations or complex changes
-- **Alembic migrations** (`alembic/versions/`): For schema version control
+- **Alembic migrations** (`alembic/versions/`): For all schema version control
+- **Alembic** handles both schema changes (adding columns, tables, indexes, etc.) and data migrations
 
 **Guidelines:**
-- **Use Alembic** for all new schema changes (adding columns, tables, indexes, etc.)
-- **Use custom scripts** for data migrations (backfilling data, one-time transformations)
-- Both can coexist, but prefer Alembic for schema changes
+- **Use Alembic** for all database changes (schema and data migrations)
+- Create migrations using `alembic revision --autogenerate` for schema changes
+- Create manual migrations using `alembic revision` for data migrations or complex operations
 
 ## Quick Reference
 

backend/docs/ARCHITECTURE.md

@@ -18,7 +18,7 @@ backend/
 │   ├── routes/            # API route blueprints
 │   ├── middleware/        # Middleware functions
 │   └── utils/             # Utility functions
-├── migrations/            # Database migration scripts
+├── alembic/               # Alembic database migrations
 ├── scripts/               # Utility scripts
 ├── toolforge/             # Toolforge deployment files
 ├── tests/                 # Test files
@@ -162,16 +162,14 @@ Routes use the `@handle_errors` decorator for consistent error handling.
 
 ## Database Migrations
 
-### Custom Migration Scripts
+The application uses **Alembic** for all database migrations:
 
-Migrations are custom Python scripts in `migrations/`:
-- Check if columns exist before adding
-- Use SQLAlchemy's `text()` for raw SQL
-- Idempotent (safe to run multiple times)
+- **Migration files**: Located in `alembic/versions/`
+- **Version tracking**: Managed by Alembic's `alembic_version` table
+- **Migration commands**: Use `alembic upgrade head` to apply migrations
+- **Auto-generation**: Use `alembic revision --autogenerate` to create migrations from model changes
 
-### Automatic Migrations
-
-Migrations run automatically on application startup via `migrate_database()` function.
+For detailed migration documentation, see [`docs/ALEMBIC_USAGE_GUIDE.md`](../docs/ALEMBIC_USAGE_GUIDE.md).
 
 ## Utility Functions
 

backend/main.py

@@ -2,80 +2,19 @@
 """
 Main entry point for running the WikiContest Flask application.
 
-This script initializes the database and starts the Flask development server.
-For production, use a WSGI server like gunicorn or uwsgi.
+This script starts the Flask API server.
 
-Usage:
-    python main.py
+Note: Database migrations are handled separately by Alembic.
 """
 
-# Third-party imports should come before local imports
-from sqlalchemy import inspect, text
-from sqlalchemy.exc import SQLAlchemyError, ProgrammingError, OperationalError
-
 # Local application imports
-from app import app, db
-
-def migrate_database():
-    """
-    Run database migrations to add new columns if they don't exist.
-    This ensures the database schema matches the current model definitions.
-    """
-    try:
-        # Get table inspector to check existing columns
-        inspector = inspect(db.engine)
-        columns = [col['name'] for col in inspector.get_columns('submissions')]
-
-        # Check which columns need to be added
-        columns_to_add = []
-        if 'article_author' not in columns:
-            columns_to_add.append(('article_author', 'VARCHAR(200) NULL'))
-        if 'article_created_at' not in columns:
-            columns_to_add.append(('article_created_at', 'VARCHAR(50) NULL'))
-        if 'article_word_count' not in columns:
-            columns_to_add.append(('article_word_count', 'INT NULL'))
-        if 'article_page_id' not in columns:
-            columns_to_add.append(('article_page_id', 'VARCHAR(50) NULL'))
-
-        # Add missing columns
-        if columns_to_add:
-            print("📦 Running database migration: Adding article metadata columns...")
-            for col_name, col_type in columns_to_add:
-                try:
-                    db.session.execute(
-                        text(f"ALTER TABLE submissions ADD COLUMN {col_name} {col_type}")
-                    )
-                    print(f"  ✓ Added column: {col_name}")
-                except (ProgrammingError, OperationalError) as error:
-                    # Column might already exist or there's a SQL/database error
-                    print(f"  ⚠ Could not add column {col_name}: {error}")
-
-            db.session.commit()
-            print("✓ Database migration completed")
-        else:
-            print("✓ Database schema is up to date")
-
-    except (OperationalError, SQLAlchemyError) as error:
-        # If table doesn't exist yet, db.create_all() will handle it
-        # Or if there's a database connection/query error
-        print(f"⚠ Migration check skipped (table may not exist yet): {error}")
-        db.session.rollback()
+from app import app
 
 if __name__ == '__main__':
     # Main application entry point.
     # This section runs when the script is executed directly (not imported).
-    # It initializes the database tables and starts the Flask development server.
-
-    # Initialize database tables
-    # This creates all tables defined in the models if they don't exist
-    with app.app_context():
-        db.create_all()
-        print("✓ Database tables initialized successfully")
 
-        # Run migrations to add new columns to existing tables
-        migrate_database()
-
-    # Start the Flask development server
+    # Start the Flask server
     # Debug mode is enabled for development (disable in production)
     print("🚀 Starting WikiContest API server...")
     print("📡 Server will be available at: http://localhost:5000")
@@ -86,4 +25,3 @@ def migrate_database():
         host='0.0.0.0',    # Allow connections from any IP
         port=5000          # Default Flask development port
     )
-