Database Migrations

Learn how to migrate your Agno database tables.

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.

If you need to apply a migration, you can use the MigrationManager class:

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 some pre-made scripts to handle your migration needs in the libs/agno/migrations directory.

The MigrationManager class supports the following databases:

• PostgreSQL
• SQLite
• MySQL
• SingleStore

You can also use the asynchronous database classes (AsyncPostgresDb and AsyncSqliteDb) with your migrations.

• 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.

How It Works

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

See the MigrationManager page for more information.

When using AgentOS, it is recommended that you run the migrations in a separate script and restart the AgentOS for the updated schema’s to take effect.

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

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.

  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.