Database Migrations

You can expect the schemas in your AgentOS 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 migration endpoints: The easiest option. 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 Migration Endpoints

There are two available endpoints:

• POST /databases/all/migrate: migrate registered local databases and report skipped remote databases.
• POST /databases/{db_id}/migrate: migrate the given local database. A RemoteDb returns 400; migrate it on the AgentOS that owns it.

Both endpoints will by default migrate tables to the latest version.

You can also migrate to a specific version by setting the target_version query parameter.

The endpoint uses the database's session-table version to choose upgrade or downgrade when a target is supplied. Review the target and take a restorable backup before calling it. Stop application writers during the v3 learning re-key and review its result before resuming writes. These routes use the runtime's configured authentication and require config:write when scope enforcement applies.

Inspect the response body, not just whether the HTTP status is in the 2xx range:

The generated OpenAPI response table does not currently declare the multi-database 207 response; the runtime still returns it on partial failure.

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.

You can read more about this in the Database Migrations page.