Skip to main content
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 downgrate your schemas.

​
Using the AgentOS Migration Endpoints

If you are using the AgentOS, you can handle your migration needs via the migration endpoints. You can read more about it in the AgentOS 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: 
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 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 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.
  • 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.
See the MigrationManager page for more information.

​
Upgrade a specific table

You can also upgrade a specific table: 
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 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: 
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 run_revert_migrations():
    await MigrationManager(db).down(target_version="2.0.0")

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

​
Troubleshooting

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.
  await MigrationManager(db).up(
      target_version="2.3.0",
      table_type="memory",
      force=True,
  )

​
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 file. You can find more information about migrating from v1 to v2 in the Migrating to Agno v2 guide.