feat: add Alembic database migrations

[harsh-kumar-patwa]

Closes #184

Summary

• Adds Alembic for versioned database schema migrations, replacing the Base.metadata.create_all() approach that cannot handle schema changes on existing databases
• Migrations run automatically on startup via init_database() — no manual steps needed for deployments
• Pre-Alembic databases (existing tables but no alembic_version) are auto-detected and stamped, so existing deployments upgrade seamlessly without data loss
• Falls back to create_all() if Alembic fails, preserving the existing graceful degradation pattern

Changes

File	Change
backend/pyproject.toml	Added alembic>=1.13.0 dependency
backend/alembic.ini	Alembic config — sqlalchemy.url left blank (set programmatically in env.py to avoid leaking credentials)
backend/src/database/alembic/env.py	Reuses existing get_database_url() and Base — no URL/model duplication
backend/src/database/alembic/script.py.mako	Standard Mako template for generating new migrations
backend/src/database/alembic/versions/0001_initial_schema.py	Initial migration matching current conversations + messages schema
backend/src/database/config.py	Added run_migrations() with auto-stamp logic; replaced inspect+create_all block with run_migrations() call + create_all fallback
backend/Makefile	Added db-migrate, db-revision, db-downgrade, db-history, db-current targets
backend/tests/test_database_config.py	Updated tests: verify run_migrations() is called + verify fallback to create_all on migration failure
README.md	Updated Database Schema section with migration commands
backend/uv.lock	Lockfile updated

How it works

1. Fresh database → alembic upgrade head creates all tables via migration
2. Existing database at head → no-op (Alembic detects nothing to do)
3. Pre-Alembic database (tables exist, no alembic_version) → auto-stamps current revision, no schema changes applied
4. Alembic failure → falls back to Base.metadata.create_all() (same behavior as before this PR)

Developer workflow for future schema changes

# 1. Modify models.py
# 2. Generate migration
make db-revision msg="add xyz column"
# 3. Review generated migration in src/database/alembic/versions/
# 4. Commit the migration file with your PR
# Migration applies automatically on next startup

Test plan

• All 343 tests pass (uv run pytest tests/ -v)
• make format && make check clean
• Fresh database: tables created via migration (verified via run_local.sh)
• Existing database at head: no-op on restart
• Pre-Alembic database: auto-stamped, data preserved
• Full stack: backend + frontend, chat streaming works, conversations persist in PostgreSQL
• Alembic CLI commands work (alembic history, alembic current)

[Copilot]

Pull request overview

Adds Alembic-based schema migrations to the backend to replace the previous Base.metadata.create_all()-only initialization approach, enabling safe evolution of existing databases while keeping “auto-init on startup” behavior.

Changes:

• Introduces Alembic configuration, env, template, and an initial 0001 schema migration.
• Updates database initialization to run migrations on startup with a create_all() fallback on failure.
• Adds Makefile migration commands and adjusts tests/docs for the new workflow.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
backend/pyproject.toml	Adds Alembic dependency.
backend/uv.lock	Locks Alembic (and transitive deps like Mako).
backend/alembic.ini	Adds Alembic config (URL set programmatically).
backend/src/database/alembic/env.py	Alembic environment wired to existing get_database_url() and Base.metadata.
backend/src/database/alembic/script.py.mako	Adds migration template for future revisions.
backend/src/database/alembic/versions/0001_initial_schema.py	Initial migration creating conversations and messages.
backend/src/database/config.py	Adds run_migrations() and calls it from init_database() with fallback behavior.
backend/tests/test_database_config.py	Updates tests to assert migration invocation and fallback to create_all().
backend/Makefile	Adds make db-* Alembic convenience targets.
README.md	Updates database schema section and documents migration commands.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[luarss]

@harsh-kumar-patwa Thanks for all your contributions! I will slowly review them as I am abit swamped currently with other matters.

ORAssistant is currently in maintenance mode - and will also not be featured in GSoC 2025. You can check this link for GSoC 2026 projects.