From 924c3f9ff605de599be682364c60ac24147cf709 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 17:13:34 +0000 Subject: [PATCH 1/8] docs: add Database Migration Documentation --- .../v0_3_to_v1_0/database/README.md | 35 +++++ .../v0_3_to_v1_0/database/simple_migration.md | 71 ++++++++++ .../v0_3_to_v1_0/database/zero_downtime.md | 130 ++++++++++++++++++ src/a2a/a2a_db_cli.py | 8 ++ src/a2a/migrations/README.md | 13 +- 5 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/migrations/v0_3_to_v1_0/database/README.md create mode 100644 docs/migrations/v0_3_to_v1_0/database/simple_migration.md create mode 100644 docs/migrations/v0_3_to_v1_0/database/zero_downtime.md diff --git a/docs/migrations/v0_3_to_v1_0/database/README.md b/docs/migrations/v0_3_to_v1_0/database/README.md new file mode 100644 index 00000000..48355c17 --- /dev/null +++ b/docs/migrations/v0_3_to_v1_0/database/README.md @@ -0,0 +1,35 @@ +# Database Migration Guide: v0.3 to v1.0 + +The A2A SDK v1.0 introduces significant updates to the database persistence layer, including a new schema for tracking task ownership and protocol versions. This guide provides the necessary steps to migrate your database from v0.3 to the v1.0 persistence model without data loss. + +--- + +## ⚡ Choose Your Migration Strategy + +Depending on your application's availability requirements, choose one of the following paths: + +| Strategy | Downtime | Complexity | Best For | +| :--- | :--- | :--- | :--- | +| **[Simple Migration](simple_migration.md)** | Short (Restart) | Low | Single-instance apps, non-critical services. | +| **[Zero Downtime Migration](zero_downtime.md)** | None | Medium | Multi-instance, high-availability production environments. | + +--- + +## 🏗ī¸ Technical Overview + +The v1.0 database migration involves: +1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` and `push_notification_configs` tables. +2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance. + +### Rollback & Safety +> [!IMPORTANT] +> +> **Data Backup**: Always perform a full snapshot of your database before starting the migration. +> **Rollback**: To revert the schema, use `uv run a2a-db downgrade -1`. + +### Verification +To verify the migration was successful: +- Tables should be updated with new columns: owner, protocol_version, last_updated. +- Inspect the `protocol_version` column in the `tasks` table; entries created before the migration should have `protocol_version` set to `NULL`, entries created during the migration should have `protocol_version` set to `0.3` (if using the zero-downtime migration strategy) and entries created after the migration should have `protocol_version` set to `1.0`. + +--- diff --git a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md new file mode 100644 index 00000000..0bad58e6 --- /dev/null +++ b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md @@ -0,0 +1,71 @@ +# 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: + +```bash +uv add "a2a-sdk[db-cli]" +# OR +pip install "a2a-sdk[db-cli]" +``` + +--- + +## 🚀 Migration Steps + +### Step 1: Apply Schema Updates +Run the `a2a-db` tool to update your tables. + +```bash +# 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](../../../../src/a2a/migrations/README.md). + +> [!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 v0.1 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: + +```bash +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. + ```bash + 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 +- **[Zero Downtime Migration](zero_downtime.md)**: If you cannot stop your application. +- **[a2a-db CLI](../../../../src/a2a/migrations/README.md)**: The primary tool for executing schema migrations. diff --git a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md new file mode 100644 index 00000000..3dca2e10 --- /dev/null +++ b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md @@ -0,0 +1,130 @@ +# Zero Downtime Migration: v0.3 to v1.0 + +This guide outlines the strategy for migrating your Agent application from A2A protocol v0.3 to v1.0 without service interruption, even when running multiple distributed instances sharing a single database. + +--- + +> [!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: + +```bash +uv add "a2a-sdk[db-cli]" +# OR +pip install "a2a-sdk[db-cli]" +``` + +--- + +## 🏗ī¸ The 3-Step Strategy + +Zero-downtime migration requires an "Expand, Migrate, Contract" pattern. It means we first expand the schema, then migrate the code to coexist with the old format, and finally transition fully to the new v1.0 standards. + +### Step 1: Expand Schema + +Apply the v1.0 schema updates to your database using the `a2a-db` migration tool. This adds new columns (`owner`, `protocol_version`, `last_updated`) while leaving existing v0.3 data intact. + +```bash +# 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](../../../../src/a2a/migrations/README.md). + +> [!NOTE] +> All new columns are nullable or have default values. Your existing v0.3 code will continue to work normally after this step is completed. +> +> Protocol v1.0 is designed to be backward compatible by default. After this step, your new v0.1 code will be able to read existing v0.3 entries from the database using a built-in legacy parser. + +#### ✅ How to Verify +Run `uv run a2a-db current` to ensure the migration was applied successfully. + +--- + +### Step 2: Rolling Deployment in Compatibility Mode + +In this step, you deploy the v1.0 SDK code but configure it to **write** data in the legacy v0.3 format. This ensures that any v0.3 instances still running in your cluster can read data produced by the new v1.0 instances. + +#### Update Initialization Code +Enable the v0.3 conversion utilities in your application entry point (e.g., `main.py`). + +```python +from a2a.server.tasks import DatabaseTaskStore, DatabasePushNotificationConfigStore +from a2a.compat.v0_3.conversions import ( + core_to_compat_task_model, + core_to_compat_push_notification_config_model, +) + +# Initialize stores with compatibility conversion +# The '... # other' represents your existing configuration (engine, table_name, etc.) +task_store = DatabaseTaskStore( + ... # other arguments + core_to_model_conversion=core_to_compat_task_model +) + +config_store = DatabasePushNotificationConfigStore( + ... # other arguments + core_to_model_conversion=core_to_compat_push_notification_config_model +) +``` + +#### Perform a Rolling Restart +Deploy the new code by restarting your instances one by one. + +#### ✅ How to Verify +Verify that v1.0 instances are successfully writing to the database. In the `tasks` and `push_notification_configs` tables, new rows created during this phase should have `protocol_version` set to `0.3`. + +--- + +### Step 3: Transition to v1.0 Mode + +Once **100%** of your application instances are running v1.0 code (with compatibility mode enabled), you can switch to the v1.0 write format. + +> [!CAUTION] +> **CRITICAL PRE-REQUISITE**: Do NOT start Step 3 until you have confirmed that no v0.3 instances remain. Old v0.3 code cannot parse the new v1.0 native database entries. + +#### Disable Compatibility Logic +Remove the `core_to_model_conversion` arguments from your Store constructors. + +```python +# Revert to native v1.0 write behavior +task_store = DatabaseTaskStore(engine=engine, ...) +config_store = DatabasePushNotificationConfigStore(engine=engine, ...) +``` + +#### Perform a Final Rolling Restart + +Restart your instances again. + +#### ✅ How to Verify +Inspect the `tasks` and `push_notification_configs` tables. New entries should now show `protocol_version` as `1.0`. + +--- + +## 🛠ī¸ Why it Works + +The A2A `DatabaseStore` classes follow a version-aware read/write pattern: + +1. **Write Logic**: If `core_to_model_conversion` is provided, it is used. Otherwise, it defaults to the v1.0 Protobuf JSON format. +2. **Read Logic**: The store automatically inspects the `protocol_version` column for every row. + * If `NULL` or `0.3`, it uses the internal **v0.3 legacy parser**. + * If `1.0`, it uses the modern **Protobuf parser**. + +This allows v1.0 instances to read *all* existing data regardless of when it was written. + + +## 🧩 Resources +- **[a2a-db CLI](../../../../src/a2a/migrations/README.md)**: The primary tool for executing schema migrations. +- **[Compatibility Conversions](../../../../src/a2a/compat/v0_3/conversions.py)**: Source for classes like `core_to_compat_task_model` used in Step 2. +- **[Task Store Implementation](../../../../src/a2a/server/tasks/database_task_store.py)**: The `DatabaseTaskStore` which handles the version-aware read/write logic. +- **[Push Notification Store Implementation](../../../../src/a2a/server/tasks/database_push_notification_config_store.py)**: The `DatabasePushNotificationConfigStore` which handles the version-aware read/write logic. + diff --git a/src/a2a/a2a_db_cli.py b/src/a2a/a2a_db_cli.py index 95dd3e75..1da69a7b 100644 --- a/src/a2a/a2a_db_cli.py +++ b/src/a2a/a2a_db_cli.py @@ -93,6 +93,12 @@ def create_parser() -> argparse.ArgumentParser: ) _add_shared_args(down_parser, is_sub=True) + # Current command + current_parser = subparsers.add_parser( + 'current', help='Display the current revision for a database' + ) + _add_shared_args(current_parser, is_sub=True) + return parser @@ -152,5 +158,7 @@ def run_migrations() -> None: elif args.cmd == 'downgrade': logging.info('Downgrading database to %s', args.revision) command.downgrade(cfg, args.revision, sql=sql) + elif args.cmd == 'current': + command.current(cfg, verbose=verbose) logging.info('Done.') diff --git a/src/a2a/migrations/README.md b/src/a2a/migrations/README.md index 593cc7f2..59899747 100644 --- a/src/a2a/migrations/README.md +++ b/src/a2a/migrations/README.md @@ -91,7 +91,18 @@ uv run a2a-db downgrade base uv run a2a-db downgrade head:base --sql ``` -Note: All flags except `--add_columns_owner_last_updated-default-owner` can be used during rollbacks. +### 6. Verifying Current Status +To see the current revision applied to your database: + +```bash +uv run a2a-db current + +# To see more details (like revision dates, if available) +uv run a2a-db current -v +``` + +> [!NOTE] +> All flags except `--add_columns_owner_last_updated-default-owner` can be used during status checks. --- From 7f9e179e59e47d7d8d853eb7e805e292ef85de2b Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 17:16:26 +0000 Subject: [PATCH 2/8] Remove duplicated disclaimers --- docs/migrations/v0_3_to_v1_0/database/README.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/migrations/v0_3_to_v1_0/database/README.md b/docs/migrations/v0_3_to_v1_0/database/README.md index 48355c17..73cc5124 100644 --- a/docs/migrations/v0_3_to_v1_0/database/README.md +++ b/docs/migrations/v0_3_to_v1_0/database/README.md @@ -21,15 +21,4 @@ The v1.0 database migration involves: 1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` and `push_notification_configs` tables. 2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance. -### Rollback & Safety -> [!IMPORTANT] -> -> **Data Backup**: Always perform a full snapshot of your database before starting the migration. -> **Rollback**: To revert the schema, use `uv run a2a-db downgrade -1`. - -### Verification -To verify the migration was successful: -- Tables should be updated with new columns: owner, protocol_version, last_updated. -- Inspect the `protocol_version` column in the `tasks` table; entries created before the migration should have `protocol_version` set to `NULL`, entries created during the migration should have `protocol_version` set to `0.3` (if using the zero-downtime migration strategy) and entries created after the migration should have `protocol_version` set to `1.0`. - --- From 9f2e788ddb5f090bb9d44c4a30979ce4bad12ca0 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 17:18:18 +0000 Subject: [PATCH 3/8] fix migration readme --- src/a2a/migrations/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/a2a/migrations/README.md b/src/a2a/migrations/README.md index 59899747..00b99f6f 100644 --- a/src/a2a/migrations/README.md +++ b/src/a2a/migrations/README.md @@ -91,6 +91,9 @@ uv run a2a-db downgrade base uv run a2a-db downgrade head:base --sql ``` +> [!NOTE] +> All flags except `--add_columns_owner_last_updated-default-owner` can be used during rollbacks. + ### 6. Verifying Current Status To see the current revision applied to your database: @@ -100,10 +103,6 @@ uv run a2a-db current # To see more details (like revision dates, if available) uv run a2a-db current -v ``` - -> [!NOTE] -> All flags except `--add_columns_owner_last_updated-default-owner` can be used during status checks. - --- ## Developer Guide for SDK Contributors From 645e6cdd9f82ae2cc9e619eca020428d84633604 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 23:18:47 +0000 Subject: [PATCH 4/8] refactor: fix typo 0.1 -> 1.0 and improve inter-consistency between two migration files --- docs/migrations/v0_3_to_v1_0/database/simple_migration.md | 7 +++++-- docs/migrations/v0_3_to_v1_0/database/zero_downtime.md | 6 +++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md index 0bad58e6..27942829 100644 --- a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md +++ b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md @@ -24,7 +24,8 @@ pip install "a2a-sdk[db-cli]" ## 🚀 Migration Steps ### Step 1: Apply Schema Updates -Run the `a2a-db` tool to update your tables. + +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. ```bash # Run migration against your target database @@ -38,9 +39,10 @@ uv run a2a-db --database-url "your-database-url" > [!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 v0.1 code will be able to read existing v0.3 entries from the database using a built-in legacy parser. +> 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: ```bash @@ -49,6 +51,7 @@ 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. --- diff --git a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md index 3dca2e10..db7483ed 100644 --- a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md +++ b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md @@ -27,9 +27,9 @@ pip install "a2a-sdk[db-cli]" Zero-downtime migration requires an "Expand, Migrate, Contract" pattern. It means we first expand the schema, then migrate the code to coexist with the old format, and finally transition fully to the new v1.0 standards. -### Step 1: Expand Schema +### Step 1: Apply Schema Updates -Apply the v1.0 schema updates to your database using the `a2a-db` migration tool. This adds new columns (`owner`, `protocol_version`, `last_updated`) while leaving existing v0.3 data intact. +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. ```bash # Run migration against your target database @@ -43,7 +43,7 @@ uv run a2a-db --database-url "your-database-url" > [!NOTE] > All new columns are nullable or have default values. Your existing v0.3 code will continue to work normally after this step is completed. > -> Protocol v1.0 is designed to be backward compatible by default. After this step, your new v0.1 code will be able to read existing v0.3 entries from the database using a built-in legacy parser. +> 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. #### ✅ How to Verify Run `uv run a2a-db current` to ensure the migration was applied successfully. From d028b2dd35657004d46636d8e573cb2808a4d304 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 23:33:06 +0000 Subject: [PATCH 5/8] refactor migration instructions to improve formating consistency --- .../v0_3_to_v1_0/database/simple_migration.md | 2 ++ docs/migrations/v0_3_to_v1_0/database/zero_downtime.md | 10 ++++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md index 27942829..4a5bab41 100644 --- a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md +++ b/docs/migrations/v0_3_to_v1_0/database/simple_migration.md @@ -2,6 +2,8 @@ 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. diff --git a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md index db7483ed..14b9de31 100644 --- a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md +++ b/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md @@ -46,9 +46,12 @@ uv run a2a-db --database-url "your-database-url" > 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. #### ✅ How to Verify -Run `uv run a2a-db current` to ensure the migration was applied successfully. +Confirm the schema is at the correct version: ---- +```bash +uv run a2a-db current +``` +The output should show the latest revision ID (e.g., `38ce57e08137`). ### Step 2: Rolling Deployment in Compatibility Mode @@ -83,8 +86,6 @@ Deploy the new code by restarting your instances one by one. #### ✅ How to Verify Verify that v1.0 instances are successfully writing to the database. In the `tasks` and `push_notification_configs` tables, new rows created during this phase should have `protocol_version` set to `0.3`. ---- - ### Step 3: Transition to v1.0 Mode Once **100%** of your application instances are running v1.0 code (with compatibility mode enabled), you can switch to the v1.0 write format. @@ -121,6 +122,7 @@ The A2A `DatabaseStore` classes follow a version-aware read/write pattern: This allows v1.0 instances to read *all* existing data regardless of when it was written. +--- ## 🧩 Resources - **[a2a-db CLI](../../../../src/a2a/migrations/README.md)**: The primary tool for executing schema migrations. From b2ae765d73ba401c714bd92fbf72a9ca8117155b Mon Sep 17 00:00:00 2001 From: sokoliva Date: Wed, 18 Mar 2026 23:36:36 +0000 Subject: [PATCH 6/8] remove trailing horizontal line in README.md file --- docs/migrations/v0_3_to_v1_0/database/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/migrations/v0_3_to_v1_0/database/README.md b/docs/migrations/v0_3_to_v1_0/database/README.md index 73cc5124..183bfb74 100644 --- a/docs/migrations/v0_3_to_v1_0/database/README.md +++ b/docs/migrations/v0_3_to_v1_0/database/README.md @@ -20,5 +20,3 @@ Depending on your application's availability requirements, choose one of the fol The v1.0 database migration involves: 1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` and `push_notification_configs` tables. 2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance. - ---- From 0a6384243f664fd3bff9c998fa214f6204ba78cb Mon Sep 17 00:00:00 2001 From: sokoliva Date: Thu, 19 Mar 2026 14:02:09 +0000 Subject: [PATCH 7/8] few small fixes --- .../{v0_3_to_v1_0 => v1_0}/database/README.md | 2 +- .../database/simple_migration.md | 14 +++++++++----- .../database/zero_downtime.md | 4 ++-- 3 files changed, 12 insertions(+), 8 deletions(-) rename docs/migrations/{v0_3_to_v1_0 => v1_0}/database/README.md (89%) rename docs/migrations/{v0_3_to_v1_0 => v1_0}/database/simple_migration.md (68%) rename docs/migrations/{v0_3_to_v1_0 => v1_0}/database/zero_downtime.md (93%) diff --git a/docs/migrations/v0_3_to_v1_0/database/README.md b/docs/migrations/v1_0/database/README.md similarity index 89% rename from docs/migrations/v0_3_to_v1_0/database/README.md rename to docs/migrations/v1_0/database/README.md index 183bfb74..76a4e3e4 100644 --- a/docs/migrations/v0_3_to_v1_0/database/README.md +++ b/docs/migrations/v1_0/database/README.md @@ -18,5 +18,5 @@ Depending on your application's availability requirements, choose one of the fol ## 🏗ī¸ Technical Overview The v1.0 database migration involves: -1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` and `push_notification_configs` tables. +1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` table and `protocol_version`, `owner` columns to the `push_notification_configs` table. 2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance. diff --git a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md b/docs/migrations/v1_0/database/simple_migration.md similarity index 68% rename from docs/migrations/v0_3_to_v1_0/database/simple_migration.md rename to docs/migrations/v1_0/database/simple_migration.md index 4a5bab41..046e4a91 100644 --- a/docs/migrations/v0_3_to_v1_0/database/simple_migration.md +++ b/docs/migrations/v1_0/database/simple_migration.md @@ -1,6 +1,6 @@ # 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. +This guide is for users who can afford a short period of downtime during the migration from A2A protocol v0.3 to v1.0. This is the recommended path for single-instance applications or non-critical services. --- @@ -39,9 +39,8 @@ uv run a2a-db --database-url "your-database-url" >For more details on the CLI migration tool, including flags, see the [A2A SDK Database Migrations README](../../../../src/a2a/migrations/README.md). > [!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. +> Database stores v1.0 are 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 @@ -62,13 +61,18 @@ Upgrade your application to use the v1.0 SDK. 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. +1. **Revert Application Code**: Revert your application code to use the v0.3 SDK. + + > [!NOTE] + > Older SDKs are compatible with the new schema (as new columns are nullable). If something breaks, rolling back the application code is usually sufficient. + +2. **Revert Schema (Fallback)**: If you encounter database issues, use the `downgrade` command to step back to the v0.3 structure. ```bash 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 diff --git a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md b/docs/migrations/v1_0/database/zero_downtime.md similarity index 93% rename from docs/migrations/v0_3_to_v1_0/database/zero_downtime.md rename to docs/migrations/v1_0/database/zero_downtime.md index 14b9de31..0deec217 100644 --- a/docs/migrations/v0_3_to_v1_0/database/zero_downtime.md +++ b/docs/migrations/v1_0/database/zero_downtime.md @@ -41,9 +41,9 @@ uv run a2a-db --database-url "your-database-url" >For more details on the CLI migration tool, including flags, see the [A2A SDK Database Migrations README](../../../../src/a2a/migrations/README.md). > [!NOTE] -> All new columns are nullable or have default values. Your existing v0.3 code will continue to work normally after this step is completed. +> All new columns are nullable. Your existing v0.3 code will continue to work normally after this step is completed. > -> 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. +> Database stores v1.0 are 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. #### ✅ How to Verify Confirm the schema is at the correct version: From b2b75a7be502c1d53509193d87fe76ae13963045 Mon Sep 17 00:00:00 2001 From: sokoliva Date: Thu, 19 Mar 2026 14:08:20 +0000 Subject: [PATCH 8/8] Grammar improvements. --- docs/migrations/v1_0/database/README.md | 2 +- docs/migrations/v1_0/database/simple_migration.md | 2 +- docs/migrations/v1_0/database/zero_downtime.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/migrations/v1_0/database/README.md b/docs/migrations/v1_0/database/README.md index 76a4e3e4..6cde621d 100644 --- a/docs/migrations/v1_0/database/README.md +++ b/docs/migrations/v1_0/database/README.md @@ -18,5 +18,5 @@ Depending on your application's availability requirements, choose one of the fol ## 🏗ī¸ Technical Overview The v1.0 database migration involves: -1. **Schema Updates**: Adding `protocol_version`, `owner`, and `last_updated` columns to the `tasks` table and `protocol_version`, `owner` columns to the `push_notification_configs` table. +1. **Schema Updates**: Adding the `protocol_version`, `owner`, and `last_updated` columns to the `tasks` table, and the `protocol_version` and `owner` columns to the `push_notification_configs` table. 2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance. diff --git a/docs/migrations/v1_0/database/simple_migration.md b/docs/migrations/v1_0/database/simple_migration.md index 046e4a91..82561f39 100644 --- a/docs/migrations/v1_0/database/simple_migration.md +++ b/docs/migrations/v1_0/database/simple_migration.md @@ -40,7 +40,7 @@ uv run a2a-db --database-url "your-database-url" > [!NOTE] > -> Database stores v1.0 are 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. +> The v1.0 database stores are 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 diff --git a/docs/migrations/v1_0/database/zero_downtime.md b/docs/migrations/v1_0/database/zero_downtime.md index 0deec217..3278c326 100644 --- a/docs/migrations/v1_0/database/zero_downtime.md +++ b/docs/migrations/v1_0/database/zero_downtime.md @@ -43,7 +43,7 @@ uv run a2a-db --database-url "your-database-url" > [!NOTE] > All new columns are nullable. Your existing v0.3 code will continue to work normally after this step is completed. > -> Database stores v1.0 are 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. +> The v1.0 database stores are 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. #### ✅ How to Verify Confirm the schema is at the correct version: