Skip to content

simple_migration.md

Latest commit

 

History

History
76 lines (51 loc) · 2.18 KB

simple_migration.md

File metadata and controls

76 lines (51 loc) · 2.18 KB

Simple Migration: v0.3 to v1.0

This guide is for users who can afford a short period of downtime (typically a few minutes) during the migration from A2A protocol v0.3 to v1.0. This is the recommended path for single-instance applications or non-critical services.

Warning

Safety First: Before proceeding, ensure you have a backup of your database.

🛠 Prerequisites

Install Migration Tools

The migration CLI is not included in the base package. Install the db-cli extra:

uv add "a2a-sdk[db-cli]"
# OR
pip install "a2a-sdk[db-cli]"

🚀 Migration Steps

Step 1: Apply Schema Updates

Run the a2a-db migration tool to update your tables. This adds new columns (owner, protocol_version, last_updated) while leaving existing v0.3 data intact.

# Run migration against your target database
uv run a2a-db --database-url "your-database-url"

Note

For more details on the CLI migration tool, including flags, see the A2A SDK Database Migrations README.

Note

All new columns are nullable or have default values.

Protocol v1.0 is designed to be backward compatible by default. After this step, your new v1.0 code will be able to read existing v0.3 entries from the database using a built-in legacy parser.

Step 2: Verify the Migration

Confirm the schema is at the correct version:

uv run a2a-db current

The output should show the latest revision ID (e.g., 38ce57e08137).

Step 3: Update Your Application Code

Upgrade your application to use the v1.0 SDK.

↩️ Rollback Strategy

If your application fails to start or encounters errors after the migration:

  1. Revert Schema: Use the downgrade command to step back to the v0.3 structure. 
    uv run a2a-db downgrade -1
  2. Reinstall v0.3 SDK: Revert your application code to the previous version.
  3. Restart: Resume operations using the v0.3 SDK.

🧩 Resources