> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-redirect-agent-platform-overview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Migrations

> Migrate Agno database tables between versions.

You can expect the schemas in your Agno database tables to be stable across versions.

However, in future versions, we may occasionally update or add new columns or tables.

To apply migrations, Agno provides two options:

* **Use the AgentOS migration endpoints**: This is the easiest option when using AgentOS. You just need to make a POST request.
* **Migrate manually using the `MigrationManager`**: If you prefer a more controlled migration experience, you can use the MigrationManager class to upgrade or downgrade your schemas.

## Using the AgentOS Migration Endpoints

If you are using the [AgentOS](/agent-os/introduction), you can handle your migration needs via the migration endpoints.

You can read more about it in the [AgentOS Database Migrations](/agent-os/usage/database-migrations) page.

## Migrate manually using the MigrationManager

All migrations are ultimately handled by the `MigrationManager` class.

You can use it directly to have total control over your migration process, or use one of the supporting scripts we provide.

Using it directly looks like this:

```python theme={null}
import asyncio

from agno.db.migrations import MigrationManager
from agno.db.postgres import AsyncPostgresDb

# The database you want to migrate
db = AsyncPostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

async def run_migrations():
    await MigrationManager(db).up()

if __name__ == "__main__":
    asyncio.run(run_migrations())
```

You can find the supporting scripts to handle your migration needs in the [`libs/agno/migrations`](https://github.com/agno-agi/agno/tree/main/libs/agno/migrations) directory.

## About the MigrationManager

The `MigrationManager`:

1. Creates an `agno_schema_versions` table to track schema versions for each table
2. Checks the current schema version of each table
3. Applies migrations in order from the current version to the target version
4. Updates the schema version record after successful migration
5. Supports both synchronous and asynchronous database operations

The following databases are supported:

* PostgreSQL
* SQLite
* MySQL
* SingleStore

You can also use the asynchronous database classes (`AsyncPostgresDb` and `AsyncSqliteDb`) are also supported.

<Tip>
  * We recommend avoiding creating columns in your database manually. This can cause the migration manager to fail.
  * Ensure the schema versions in the `agno_schema_versions` table are correct.
</Tip>

See the [MigrationManager](/reference/storage/migrations) page for more information.

### Upgrade a specific table

You can also upgrade a specific table:

```python theme={null}
import asyncio

from agno.db.migrations import MigrationManager
from agno.db.postgres import AsyncPostgresDb

# The database you want to migrate
db = AsyncPostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

async def run_migrate_table():
    # This will migrate the memories table to the latest version
    await MigrationManager(db).up(table_type="memory")

    # Or if you want to upgrade to a specific version
    await MigrationManager(db).up(table_type="memory", target_version="2.0.0")

    # Or if you want to force the migration
    await MigrationManager(db).up(table_type="memory", force=True)

if __name__ == "__main__":
    asyncio.run(run_migrate_table())
```

The supported table types are: `session`, `memory`, `metrics`, `eval`, `knowledge`, `culture`.

### Reverting Migrations

You can also use the `MigrationManager` class to revert a migration:

```python theme={null}
import asyncio

from agno.db.migrations import MigrationManager
from agno.db.postgres import AsyncPostgresDb

# The database you want to migrate
db = AsyncPostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

async def run_revert_migrations():
    await MigrationManager(db).down(target_version="2.0.0")

if __name__ == "__main__":
    asyncio.run(run_revert_migrations())
```

## Troubleshooting

<Tabs>
  <Tab title="Schema mismatch errors">
    If you continue to see errors and are not able to read or write to the database, it's likely due to a mismatch between the schema version and the actual schema of the table.

    Please set the `force` parameter to `True` to force the migration for a specific table.

    ```python theme={null}
      await MigrationManager(db).up(
          target_version="2.3.0",
          table_type="memory",
          force=True,
      )
    ```
  </Tab>

  <Tab title="Invalid Column Errors">
    Ensure you have run the migration before using the updated `agno` code in production.
  </Tab>

  <Tab title="SQL INSERT Errors">
    If you are facing SQL INSERT errors when using your database, ensure that you have run the latest migrations AND you restarted your AgentOS instance.
  </Tab>
</Tabs>

## Migrating from Agno v1 to v2

If you started using Agno during its v1 and want to move to v2, we have a migration script that can help you update your database tables.

You can find the script in the [`libs/agno/migrations/v1_to_v2/migrate_to_v2.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/migrations/v1_to_v2/migrate_to_v2.py) file.

You can find more information about migrating from v1 to v2 in the [Migrating to Agno v2 guide](/other/v2-migration).