MigrationManager

API reference for the MigrationManager class used to handle database migrations.

The MigrationManager class provides a programmatic way to manage database schema migrations for Agno database tables.

Constructor

MigrationManager(db: Union[AsyncBaseDb, BaseDb])

Parameters

dbUnion[AsyncBaseDb, BaseDb]required

The database instance to run migrations on. Supports both synchronous and asynchronous database classes.

Properties

latest_schema_versionVersion

Returns the latest available schema version from the migration versions list.

available_versionslist[tuple[str, Version]]

A list of available migration versions as tuples of (version_string, parsed_version).

Currently available versions:

  • v2_0_0 (2.0.0)
  • v2_3_0 (2.3.0)
  • v2_5_0 (2.5.0)
  • v2_5_6 (2.5.6)
  • v3_0_0 (3.0.0, the latest schema version)

Methods

up()

Executes upgrade migrations to bring database tables to a target schema version.

async def up(
    target_version: Optional[str] = None,
    table_type: Optional[str] = None,
    force: bool = False
)

Parameters

target_versionstroptional

The version to migrate to (e.g., "2.3.0"). If not provided, migrates to the latest available version.

table_typestroptional

The specific table type to migrate. If not provided, all tables will be migrated.

Valid values: "memories", "sessions", "metrics", "evals", "knowledge", "approvals", "components", "schedules", "schedule_runs", "learnings".

forcebooldefault: False

Bypass the initial version-skip check. Migration steps still run only when newer than the recorded table version; this does not reapply an already stamped migration or repair an incorrect stamp. Tables with no reported schema version are skipped even with force=True.

Example

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

db = AsyncPostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

async def run_migrations():
    # Migrate all tables to latest version
    await MigrationManager(db).up()

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

down()

Executes downgrade migrations to revert database tables to a target schema version.

async def down(
    target_version: str,
    table_type: Optional[str] = None,
    force: bool = False
)

Parameters

target_versionstrrequired

The version to migrate down to (e.g., "2.0.0"). This parameter is required for down migrations.

table_typestroptional

The specific table type to migrate. If not provided, all tables will be migrated.

Valid values: "memories", "sessions", "metrics", "evals", "knowledge", "approvals", "components", "schedules", "schedule_runs", "learnings".

forcebooldefault: False

Force the migration even if the current version is equal to or less than the target version.

Example

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

db = AsyncPostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

async def revert_migrations():
    # Revert all tables to version 2.0.0
    await MigrationManager(db).down(target_version="2.0.0")
    
    # Revert specific table
    await MigrationManager(db).down(
        target_version="2.0.0",
        table_type="memories"
    )

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

Supported Databases

Install your adapter's dependencies and configure a reachable database before running these examples. The URLs above are placeholders. Take a restorable backup before schema changes.

The v3.0 migration supports these database types; support for earlier migrations depends on the migration version:

  • PostgreSQL (via PostgresDb or AsyncPostgresDb)
  • SQLite (via SqliteDb or AsyncSqliteDb)
  • MySQL (via MySQLDb or AsyncMySQLDb)
  • SingleStore (via SingleStoreDb)
  • MongoDB (via MongoDb or AsyncMongoDb)
  • Firestore, Redis, Valkey, DynamoDB, and SurrealDB
  • JSON, Google Cloud Storage JSON, and in-memory storage

The v3 learning entity-memory re-key is irreversible: down() leaves those learnings unchanged. An upgrade followed by a downgrade does not restore their old shared keys.

Table Types

The following table types can be migrated:

Table TypeDescription
memoriesUser memory storage
sessionsAgent, team, and workflow session data
metricsPerformance and usage metrics
evalsEvaluation results
knowledgeKnowledge base entries
approvalsHuman-in-the-loop approval records
componentsStored component definitions
schedulesSchedule definitions
schedule_runsSchedule execution records
learningsLearning records, including the v3 entity-memory re-key

See Also