docs: add Database Migration Documentation#864
docs: add Database Migration Documentation#864sokoliva wants to merge 6 commits intoa2aproject:1.0-devfrom
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly improves the A2A SDK's documentation by providing comprehensive guides for migrating databases from version 0.3 to 1.0. It offers clear, step-by-step instructions for both simple and zero-downtime migration scenarios, ensuring data integrity and operational continuity. Additionally, the Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
🧪 Code Coverage (vs
|
| Base | PR | Delta | |
|---|---|---|---|
| src/a2a/a2a_db_cli.py | 97.22% | 92.31% | 🔴 -4.91% |
| Total | 90.29% | 90.24% | 🔴 -0.04% |
Generated by coverage-comment.yml
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds comprehensive documentation for database migrations from v0.3 to v1.0, including guides for both simple and zero-downtime strategies. It also enhances the a2a-db CLI tool by adding a current command to display the current database revision.
The documentation is well-structured and detailed. I've found a few minor inaccuracies and typos that could confuse users, and I've provided suggestions to correct them. I also have a couple of suggestions to improve the clarity of the CLI tool's usage and its documentation. Overall, this is a great addition to the project.
I am having trouble creating individual review comments. Click here to see my feedback.
docs/migrations/v0_3_to_v1_0/database/README.md (21)
The documentation states that the last_updated column is added to both the tasks and push_notification_configs tables. However, based on the migration scripts, it is only added to the tasks table. Please update the documentation for accuracy.
docs/migrations/v0_3_to_v1_0/database/simple_migration.md (41)
There's a typo in the version number. It should be v1.0 code, not v0.1.
> Protocol 1.0 is designed to be backward compatible by default. After this step, your new 1.0 code will be able to read existing 0.3 entries from the database using a built-in legacy parser.
References
- For consistency in link text for protocol versions, prefer the shorter major/minor format (e.g., '0.3') over the full version format (e.g., 'v0.3.0').
docs/migrations/v0_3_to_v1_0/database/zero_downtime.md (46)
There's a typo in the version number. It should be v1.0 code, not v0.1.
> Protocol 1.0 is designed to be backward compatible by default. After this step, your new 1.0 code will be able to read existing 0.3 entries from the database using a built-in legacy parser.
References
- For consistency in link text for protocol versions, prefer the shorter major/minor format (e.g., '0.3') over the full version format (e.g., 'v0.3.0').
docs/migrations/v0_3_to_v1_0/database/README.md (33)
This line is quite long and contains a lot of information. For better readability, consider rephrasing it to be more concise.
- Inspect the `protocol_version` column in the `tasks` table. The value depends on when the entry was created: `NULL` (before migration), `0.3` (during zero-downtime migration), or `1.0` (after migration).
References
- Documentation should be concise, providing only necessary and exact steps, and avoiding superfluous information or commands that are not strictly required.
src/a2a/a2a_db_cli.py (100)
The current command doesn't use the --sql flag, but it's being added via _add_shared_args. This could be confusing for users as the flag will appear in the help message but have no effect. Consider adding only the relevant arguments for this command to avoid showing an unused flag.
src/a2a/migrations/README.md (105)
This note is a bit ambiguous because some flags can be passed but are ignored by the current command (e.g., --sql). To avoid confusion, it would be clearer to explicitly list the flags that are relevant to this command.
> The `current` command supports the `--database-url`, `--tasks-table`, `--push-notification-configs-table`, and `--verbose` (`-v`) flags.
References
- Documentation should be concise, providing only necessary and exact steps, and avoiding superfluous information or commands that are not strictly required.
| 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. |
There was a problem hiding this comment.
is the last_updated field added to both?
There was a problem hiding this comment.
No, but I felt like pointing that out would be an unnecessary overkill. I will make the distinction to avoid confusion.
| @@ -0,0 +1,76 @@ | |||
| # 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. | |||
There was a problem hiding this comment.
i would not add the 'typically a few minutes' sentence, as it depends on each use case
There was a problem hiding this comment.
Let's do v0_3_to_v1_0 -> 1.0 - the migration guide is always from the previous to current, if one needs to migrate from 0.3 to 2.0 they will have to follow them sequentially.
| 1. **Revert Schema**: Use the `downgrade` command to step back to the v0.3 structure. | ||
| ```bash | ||
| uv run a2a-db downgrade -1 | ||
| ``` |
There was a problem hiding this comment.
Old SDK should work with the new schema, let's mention this here. In theory if something stopped working code rollback should be enough. We should also mention DB rollback but it's rather for the "unknown unknowns", we don't expect new columns to affect old SDKs.
| > [!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 v1.0 code will be able to read existing v0.3 entries from the database using a built-in legacy parser. |
There was a problem hiding this comment.
nit: protocol itself is not compatible, it's rather DB backed stores implementations in the new SDK.
3 participants
Description
Add documentation about database migrations for users.
Add
currentoption to thea2a-dbCLI command to see current version of the database.CONTRIBUTINGGuide.fix:which represents bug fixes, and correlates to a SemVer patch.feat:represents a new feature, and correlates to a SemVer minor.feat!:, orfix!:,refactor!:, etc., which represent a breaking change (indicated by the!) and will result in a SemVer major.bash scripts/format.shfrom the repository root to format)Fixes #715 🦕