Dongyu Jia
338c3c89c6
This change introduces a sample (`migration_session_db`) demonstrating how to load a session database created with an older version of ADK (e.g., 1.15.0) and make it compatible with the current version. It includes a script (`db_migration.sh`) to alter the SQLite schema automatically. to_event is updated to handle potential discrepancies in pickled `EventActions` by using `model_copy` to ensure compatibility with the latest `EventActions` model definition. Related to #3272 #3197, Closes #3197 #3272 Co-authored-by: Dongyu Jia <dongyuj@google.com> PiperOrigin-RevId: 826524368
Loading and Upgrading Old Session Databases
This example demonstrates how to upgrade a session database created with an older version of ADK to be compatible with the current version.
Sample Database
This sample includes dnd_sessions.db, a database created with ADK v1.15.0. The following steps show how to run into a schema error and then resolve it using the migration script.
1. Reproduce the Error
First, copy the old database to sessions.db, which is the file the sample application expects.
cp dnd_sessions.db sessions.db
python main.py
Running the application against the old database will fail with a schema mismatch error, as the events table is missing a column required by newer ADK versions:
sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such column: events.usage_metadata
2. Upgrade the Database Schema
ADK provides a migration script to update the database schema. Run the following command to download and execute it.
# Clean up the previous run before executing the migration
cp dnd_sessions.db sessions.db
# Download and run the migration script
curl -fsSL https://raw.githubusercontent.com/google/adk-python/main/scripts/db_migration.sh | sh -s -- "sqlite:///%(here)s/sessions.db" "google.adk.sessions.database_session_service"
This script uses alembic to compare the existing schema against the current model definition and automatically generates and applies the necessary migrations.
Note on generated files:
- The script will create an
alembic.inifile and analembic/directory. You must delete these before re-running the script. - The
sample-outputdirectory in this example contains a reference of the generated files for your inspection. - The
%(here)svariable in the database URL is analembicplaceholder that refers to the current directory.
3. Run the Agent Successfully
With the database schema updated, the application can now load the session correctly.
python main.py
You should see output indicating that the old session was successfully loaded.
Limitations
The migration script is designed to add new columns that have been introduced in newer ADK versions. It does not handle more complex schema changes, such as modifying a column's data type (e.g., from int to string) or altering the internal structure of stored data.