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

> Seamlessly migrate your AI Hedge Fund application between versions using Alembic commands. Upgrade or downgrade your SQLite database schema effortlessly. Learn how now.

- Repository: [Virat Singh/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)
- Tags: migration-guide
- Published: 2026-03-09

---

**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`](https://github.com/virattt/ai-hedge-fund/blob/main/alembic.ini)** – Defines the database URL and script location. By default, it points to `sqlite:///./hedge_fund.db`.
- **[`env.py`](https://github.com/virattt/ai-hedge-fund/blob/main/env.py)** – Loads the SQLAlchemy metadata (`Base`) from [`app/backend/database/models.py`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/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):

```bash
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`](https://github.com/virattt/ai-hedge-fund/blob/main/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:

```bash
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):

```bash
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:

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

```

To see the full history of available migrations:

```bash
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`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/app/backend/database/models.py).

2. **Generate the migration**:

   ```bash
   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**:

   ```bash
   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:

```bash
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:

```bash
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`](https://github.com/virattt/ai-hedge-fund/blob/main/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.