How to Migrate Between Different Versions of the AI Hedge Fund Application

Use Alembic commands to upgrade or downgrade the SQLite database schema by running poetry run alembic -c app/backend/alembic.ini upgrade head to move forward or downgrade -1 to revert.

The virattt/ai-hedge-fund application uses Alembic to manage database schema changes across versions. When you migrate between different versions of the application, you must synchronize the SQLite database (hedge_fund.db) with the expected schema using revision scripts stored in app/backend/alembic/versions/.

Understanding the Migration Architecture

Before executing commands to migrate between different versions, understand how the components interact.

Core Configuration Files

The migration system relies on two critical configuration files in app/backend/alembic/:

• alembic.ini – Defines the database URL and script location. By default, it points to sqlite:///./hedge_fund.db.
• env.py – Loads the SQLAlchemy metadata (Base) from app/backend/database/models.py, enabling Alembic to autogenerate migrations based on model changes.

Database Connection and Models

The actual database engine is created in app/backend/database/connection.py. Both the application and Alembic use this connection logic. When you run migration commands, Alembic reads the current state from the alembic_version table inside hedge_fund.db and determines which revision scripts in app/backend/alembic/versions/ need to be applied or reverted.

How to Migrate Between Different Versions

Upgrade to the Latest Version

To move your database schema to the newest version (the head revision):

poetry run alembic -c app/backend/alembic.ini upgrade head

This command executes the upgrade() function in every pending revision file found in app/backend/alembic/versions/, such as add_api_keys_table.py, bringing the database schema up to date.

Downgrade to a Previous Version

If you need to migrate between different versions by reverting changes, use the downgrade command.

To step back exactly one version:

poetry run alembic -c app/backend/alembic.ini downgrade -1

To downgrade to a specific revision identifier (found at the top of each migration file):

poetry run alembic -c app/backend/alembic.ini downgrade 3f9a6b7c8d2e

This executes the downgrade() function in the corresponding revision files, reversing schema changes like dropping tables or removing columns.

Check Current Version Status

Before you migrate between different versions, verify which revision is currently active:

poetry run alembic -c app/backend/alembic.ini current

To see the full history of available migrations:

poetry run alembic -c app/backend/alembic.ini history --verbose

Creating New Migrations for Custom Versions

When you modify SQLAlchemy models in app/backend/database/models.py, you must generate a new revision to migrate between your custom version and the existing schema.

1. Update your models in app/backend/database/models.py.

2. Generate the migration:

   poetry run alembic -c app/backend/alembic.ini revision --autogenerate -m "Add new table X"

3. Review the generated file in app/backend/alembic/versions/. Alembic scaffolds upgrade() and downgrade() functions based on the difference between current models and the database state.

4. Apply the migration:

   poetry run alembic -c app/backend/alembic.ini upgrade head

Handling Migration Errors and Edge Cases

Custom Database Paths

If you store hedge_fund.db outside the project root, set the SQLALCHEMY_URL environment variable before running Alembic commands:

export SQLALCHEMY_URL="sqlite:///$(pwd)/my_custom_path/hedge_fund.db"
poetry run alembic -c app/backend/alembic.ini upgrade head

Stamping the Database

If you encounter "Target database is not up to date" errors after manual database edits, you can mark the database as current without running migrations:

poetry run alembic -c app/backend/alembic.ini stamp head

Use this command with caution; it updates the alembic_version table without executing upgrade() or downgrade() logic.

Summary

• Alembic manages schema changes in virattt/ai-hedge-fund through revision scripts stored in app/backend/alembic/versions/.
• To migrate between different versions, use poetry run alembic -c app/backend/alembic.ini upgrade head to move forward or downgrade -1 to revert.
• Always check current status with current and review migration history with history --verbose before switching versions.
• For custom database paths, export SQLALCHEMY_URL before running Alembic commands.

Frequently Asked Questions

How do I check which version of the database schema is currently applied?

Run poetry run alembic -c app/backend/alembic.ini current to display the active revision ID stored in the alembic_version table. This helps you verify the current state before you migrate between different versions.

Can I skip specific migrations when upgrading?

No, Alembic applies migrations sequentially based on the dependency chain defined in each revision file's down_revision attribute. To skip a migration, you must manually edit the revision scripts or use stamp to mark the database as current, though this is not recommended for production environments.

What happens if I delete the hedge_fund.db file?

Deleting the SQLite file removes both your data and the alembic_version table. The next time you run upgrade head, Alembic will treat the database as brand-new and execute all migration scripts in app/backend/alembic/versions/, effectively recreating the schema from scratch.

How do I create a migration for my own model changes?

After modifying app/backend/database/models.py, run poetry run alembic -c app/backend/alembic.ini revision --autogenerate -m "Description of changes". Alembic compares your SQLAlchemy models against the current database schema and generates a new Python file in app/backend/alembic/versions/ containing the upgrade() and downgrade() functions. Always review the generated script before applying it.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}