This directory handles the database schema updates for the A2A SDK. It uses a bundled CLI tool to simplify the migration process.
To use the a2a-db migration tool, install the a2a-sdk with the db-cli extra.
| Extra | uv Command |
pip Command |
|---|---|---|
| CLI Only | uv add "a2a-sdk[db-cli]" |
pip install "a2a-sdk[db-cli]" |
| All Extras | uv add "a2a-sdk[all]" |
pip install "a2a-sdk[all]" |
When you install the a2a-sdk, you get a built-in command a2a-db which updates your database to make it compatible with the latest version of the SDK.
Before running migrations, it is recommended to back up your database.
Migrations require the DATABASE_URL environment variable to be set with an async-compatible driver.
You can set it globally with export DATABASE_URL. Examples for SQLite, PostgreSQL and MySQL, respectively:
export DATABASE_URL="sqlite+aiosqlite://user:pass@host:port/your_database_name"
export DATABASE_URL="postgresql+asyncpg://user:pass@localhost/your_database_name"
export DATABASE_URL="mysql+aiomysql://user:pass@localhost/your_database_name"
Or you can use the --database-url flag to specify the database URL for a single command.
Always run this command after installing or upgrading the SDK to ensure your database matches the required schema. This will upgrade the tables tasks and push_notification_configs in your database by adding columns owner and last_updated and an index (owner, last_updated) to the tasks table and a column owner to the push_notification_configs table.
Revision b5e3d1c8a2f7 creates two additive tables, task_versions and task_events, used only by the clustered multi-server stores (a2a.server.cluster). It leaves the tasks table untouched, so deployments that use the default DatabaseTaskStore need not run it and are unaffected. Run it only when adopting a VersionedTaskStore for multi-server deployment.
uv run a2a-db
Allows you to pass custom values for the new owner column. If not set, it will default to the value legacy_v03_no_user_info.
uv run a2a-db --add_columns_owner_last_updated-default-owner "admin_user"
You can use the --database-url flag to specify the database URL for a single command.
uv run a2a-db --database-url "sqlite+aiosqlite:///my_database.db"
Custom tasks and push notification configs tables to update. If not set, the default are tasks and push_notification_configs.
uv run a2a-db --tasks-table "my_tasks" --push-notification-configs-table "my_configs"
Enables verbose output by setting sqlalchemy.engine logging to INFO.
uv run a2a-db -v
Enables running migrations in offline mode. Migrations are generated as SQL scripts and printed to stdout instead of being run against the database.
uv run a2a-db --sql
If you need to revert a change:
# Step back one version
uv run a2a-db downgrade -1
# Downgrade to a specific revision ID
uv run a2a-db downgrade <revision_id>
# Revert all migrations
uv run a2a-db downgrade base
# Revert all migrations in offline mode
uv run a2a-db downgrade head:base --sql
[!NOTE] All flags except
--add_columns_owner_last_updated-default-ownercan be used during rollbacks.
To see the current revision applied to your database:
uv run a2a-db current
# To see more details (like revision dates, if available)
uv run a2a-db current -v
If you are modifying the SDK models and need to generate new migration files, use the following workflow.
Developers should use the raw alembic command locally to generate migrations. Ensure you are in the project root.
# Detect changes in models.py and generate a script
uv run alembic revision --autogenerate -m "description of changes"
env.py: Configures the migration engine and applies the mandatory DATABASE_URL check.versions/: Contains the migration history.script.py.mako: The template for all new migration files.