Skip to content

Commit 773a7c9

Browse files
ishymkoishymko
authored
Merge branch '1.0-dev' into ishymko/845-validation
2 parents b891f34 + fd12dff commit 773a7c9

5 files changed

Lines changed: 253 additions & 1 deletion

File tree

‎docs/migrations/v1_0/database/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Database Migration Guide: v0.3 to v1.0
2+
3+
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.
4+
5+
---
6+
7+
## ⚡ Choose Your Migration Strategy
8+
9+
Depending on your application's availability requirements, choose one of the following paths:
10+
11+
| Strategy | Downtime | Complexity | Best For |
12+
| :--- | :--- | :--- | :--- |
13+
| **[Simple Migration](simple_migration.md)** | Short (Restart) | Low | Single-instance apps, non-critical services. |
14+
| **[Zero Downtime Migration](zero_downtime.md)** | None | Medium | Multi-instance, high-availability production environments. |
15+
16+
---
17+
18+
## 🏗️ Technical Overview
19+
20+
The v1.0 database migration involves:
21+
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.
22+
2. **Storage Model**: Transitioning from Pydantic-based JSON to Protobuf-based JSON serialization for better interoperability and performance.

‎docs/migrations/v1_0/database/simple_migration.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Simple Migration: v0.3 to v1.0
2+
3+
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.
4+
5+
---
6+
7+
> [!WARNING]
8+
> **Safety First:**
9+
> Before proceeding, ensure you have a backup of your database.
10+
11+
---
12+
13+
## 🛠 Prerequisites
14+
15+
### Install Migration Tools
16+
The migration CLI is not included in the base package. Install the `db-cli` extra:
17+
18+
```bash
19+
uv add "a2a-sdk[db-cli]"
20+
# OR
21+
pip install "a2a-sdk[db-cli]"
22+
```
23+
24+
---
25+
26+
## 🚀 Migration Steps
27+
28+
### Step 1: Apply Schema Updates
29+
30+
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.
31+
32+
```bash
33+
# Run migration against your target database
34+
uv run a2a-db --database-url "your-database-url"
35+
```
36+
37+
> [!NOTE]
38+
>
39+
>For more details on the CLI migration tool, including flags, see the [A2A SDK Database Migrations README](../../../../src/a2a/migrations/README.md).
40+
41+
> [!NOTE]
42+
>
43+
> 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.
44+
45+
### Step 2: Verify the Migration
46+
47+
Confirm the schema is at the correct version:
48+
49+
```bash
50+
uv run a2a-db current
51+
```
52+
The output should show the latest revision ID (e.g., `38ce57e08137`).
53+
54+
### Step 3: Update Your Application Code
55+
56+
Upgrade your application to use the v1.0 SDK.
57+
58+
---
59+
60+
## ↩️ Rollback Strategy
61+
62+
If your application fails to start or encounters errors after the migration:
63+
64+
1. **Revert Application Code**: Revert your application code to use the v0.3 SDK.
65+
66+
> [!NOTE]
67+
> Older SDKs are compatible with the new schema (as new columns are nullable). If something breaks, rolling back the application code is usually sufficient.
68+
69+
2. **Revert Schema (Fallback)**: If you encounter database issues, use the `downgrade` command to step back to the v0.3 structure.
70+
```bash
71+
uv run a2a-db downgrade -1
72+
```
73+
3. **Restart**: Resume operations using the v0.3 SDK.
74+
75+
76+
---
77+
78+
## 🧩 Resources
79+
- **[Zero Downtime Migration](zero_downtime.md)**: If you cannot stop your application.
80+
- **[a2a-db CLI](../../../../src/a2a/migrations/README.md)**: The primary tool for executing schema migrations.

‎docs/migrations/v1_0/database/zero_downtime.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Zero Downtime Migration: v0.3 to v1.0
2+
3+
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.
4+
5+
---
6+
7+
> [!WARNING]
8+
> **Safety First:**
9+
> Before proceeding, ensure you have a backup of your database.
10+
11+
---
12+
13+
## 🛠 Prerequisites
14+
15+
### Install Migration Tools
16+
The migration CLI is not included in the base package. Install the `db-cli` extra:
17+
18+
```bash
19+
uv add "a2a-sdk[db-cli]"
20+
# OR
21+
pip install "a2a-sdk[db-cli]"
22+
```
23+
24+
---
25+
26+
## 🏗️ The 3-Step Strategy
27+
28+
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.
29+
30+
### Step 1: Apply Schema Updates
31+
32+
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.
33+
34+
```bash
35+
# Run migration against your target database
36+
uv run a2a-db --database-url "your-database-url"
37+
```
38+
39+
> [!NOTE]
40+
>
41+
>For more details on the CLI migration tool, including flags, see the [A2A SDK Database Migrations README](../../../../src/a2a/migrations/README.md).
42+
43+
> [!NOTE]
44+
> All new columns are nullable. Your existing v0.3 code will continue to work normally after this step is completed.
45+
>
46+
> 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.
47+
48+
#### ✅ How to Verify
49+
Confirm the schema is at the correct version:
50+
51+
```bash
52+
uv run a2a-db current
53+
```
54+
The output should show the latest revision ID (e.g., `38ce57e08137`).
55+
56+
### Step 2: Rolling Deployment in Compatibility Mode
57+
58+
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.
59+
60+
#### Update Initialization Code
61+
Enable the v0.3 conversion utilities in your application entry point (e.g., `main.py`).
62+
63+
```python
64+
from a2a.server.tasks import DatabaseTaskStore, DatabasePushNotificationConfigStore
65+
from a2a.compat.v0_3.conversions import (
66+
core_to_compat_task_model,
67+
core_to_compat_push_notification_config_model,
68+
)
69+
70+
# Initialize stores with compatibility conversion
71+
# The '... # other' represents your existing configuration (engine, table_name, etc.)
72+
task_store = DatabaseTaskStore(
73+
... # other arguments
74+
core_to_model_conversion=core_to_compat_task_model
75+
)
76+
77+
config_store = DatabasePushNotificationConfigStore(
78+
... # other arguments
79+
core_to_model_conversion=core_to_compat_push_notification_config_model
80+
)
81+
```
82+
83+
#### Perform a Rolling Restart
84+
Deploy the new code by restarting your instances one by one.
85+
86+
#### ✅ How to Verify
87+
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`.
88+
89+
### Step 3: Transition to v1.0 Mode
90+
91+
Once **100%** of your application instances are running v1.0 code (with compatibility mode enabled), you can switch to the v1.0 write format.
92+
93+
> [!CAUTION]
94+
> **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.
95+
96+
#### Disable Compatibility Logic
97+
Remove the `core_to_model_conversion` arguments from your Store constructors.
98+
99+
```python
100+
# Revert to native v1.0 write behavior
101+
task_store = DatabaseTaskStore(engine=engine, ...)
102+
config_store = DatabasePushNotificationConfigStore(engine=engine, ...)
103+
```
104+
105+
#### Perform a Final Rolling Restart
106+
107+
Restart your instances again.
108+
109+
#### ✅ How to Verify
110+
Inspect the `tasks` and `push_notification_configs` tables. New entries should now show `protocol_version` as `1.0`.
111+
112+
---
113+
114+
## 🛠️ Why it Works
115+
116+
The A2A `DatabaseStore` classes follow a version-aware read/write pattern:
117+
118+
1. **Write Logic**: If `core_to_model_conversion` is provided, it is used. Otherwise, it defaults to the v1.0 Protobuf JSON format.
119+
2. **Read Logic**: The store automatically inspects the `protocol_version` column for every row.
120+
* If `NULL` or `0.3`, it uses the internal **v0.3 legacy parser**.
121+
* If `1.0`, it uses the modern **Protobuf parser**.
122+
123+
This allows v1.0 instances to read *all* existing data regardless of when it was written.
124+
125+
---
126+
127+
## 🧩 Resources
128+
- **[a2a-db CLI](../../../../src/a2a/migrations/README.md)**: The primary tool for executing schema migrations.
129+
- **[Compatibility Conversions](../../../../src/a2a/compat/v0_3/conversions.py)**: Source for classes like `core_to_compat_task_model` used in Step 2.
130+
- **[Task Store Implementation](../../../../src/a2a/server/tasks/database_task_store.py)**: The `DatabaseTaskStore` which handles the version-aware read/write logic.
131+
- **[Push Notification Store Implementation](../../../../src/a2a/server/tasks/database_push_notification_config_store.py)**: The `DatabasePushNotificationConfigStore` which handles the version-aware read/write logic.
132+

‎src/a2a/a2a_db_cli.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,12 @@ def create_parser() -> argparse.ArgumentParser:
9393
)
9494
_add_shared_args(down_parser, is_sub=True)
9595

96+
# Current command
97+
current_parser = subparsers.add_parser(
98+
'current', help='Display the current revision for a database'
99+
)
100+
_add_shared_args(current_parser, is_sub=True)
101+
96102
return parser
97103

98104

@@ -152,5 +158,7 @@ def run_migrations() -> None:
152158
elif args.cmd == 'downgrade':
153159
logging.info('Downgrading database to %s', args.revision)
154160
command.downgrade(cfg, args.revision, sql=sql)
161+
elif args.cmd == 'current':
162+
command.current(cfg, verbose=verbose)
155163

156164
logging.info('Done.')

‎src/a2a/migrations/README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,18 @@ uv run a2a-db downgrade base
9191
uv run a2a-db downgrade head:base --sql
9292
```
9393

94-
Note: All flags except `--add_columns_owner_last_updated-default-owner` can be used during rollbacks.
94+
> [!NOTE]
95+
> All flags except `--add_columns_owner_last_updated-default-owner` can be used during rollbacks.
9596
97+
### 6. Verifying Current Status
98+
To see the current revision applied to your database:
99+
100+
```bash
101+
uv run a2a-db current
102+
103+
# To see more details (like revision dates, if available)
104+
uv run a2a-db current -v
105+
```
96106
---
97107

98108
## Developer Guide for SDK Contributors

0 commit comments

Comments
 (0)