Need migration to update Database on new releases

Problem Description
When upgrading the ADK Python library from release 0.1.0 to 0.3.0, no database migration scripts or upgrade instructions were provided for users who initially started on version 0.1.0. The new version introduces additional columns in several tables, but the library does not automatically update the schema or guide users through a manual migration. As a result, attempts to insert data into the in-memory database fail with “unknown column” or similar errors.

Steps to Reproduce

Install adk-python v0.1.0 and initialize a session, which creates the in-memory database schema.

Insert or query some StorageEvent, Session, or other entities—everything works as expected.

Upgrade your environment to adk-python v0.3.0 (e.g., pip install --upgrade adk-python).

Restart your application and attempt to insert new events or sessions.

Expected Behavior
Upgrading the library should either:

Automatically apply a migration to add the new columns to existing databases, or

Include explicit migration scripts (e.g., Alembic revisions) and clear instructions in the CHANGELOG or README guiding users through a manual alembic upgrade head (or equivalent) process.

Actual Behavior
No migrations are included in the package, and there are no documented instructions for updating an existing database schema. Consequently, the code attempts to write to columns that don’t exist, resulting in runtime errors.

Proposed Fix

Add migration scripts

Use Alembic (or another migrations tool) to generate revisions for all schema changes introduced between 0.1.0 and 0.3.0.

Include these migration files in the adk-python repository under an appropriate migrations/ directory.

Document the upgrade path

Update the CHANGELOG.md and README.md to include a section for “Upgrading from v0.1.0 to v0.3.0,” showing the commands needed to apply migrations.

Example in README:

markdown
Copy
Edit

Upgrading from v0.1.0 to v0.3.0

pip install --upgrade adk-python
alembic upgrade head
Copy
Edit
Optional: Runtime schema check

On application startup, detect if the database schema is out of date and log a warning if migrations have not been applied.

@JoaoCampista

Hi @JoaoCampista , thanks for your suggestion, we are finalizing our db schema, and we will avoid breaking schema changes in the future. For any breaking changes going forward, we will emphasize in the release log and add migration plan if possible.

similar error also occurs when upgrading from release 1.16.0 to 1.17.0
(psycopg2.errors.UndefinedColumn) column events.usage_metadata does not exist
LINE 1: ...events.custom_metadata AS events_custom_metadata, events.usa...
^

[SQL: SELECT events.id AS events_id, events.app_name AS events_app_name, events.user_id AS events_user_id, events.session_id AS events_session_id, events.invocation_id AS events_invocation_id, events.author AS events_author, events.actions AS events_actions, events.long_running_tool_ids_json AS events_long_running_tool_ids_json, events.branch AS events_branch, events.timestamp AS events_timestamp, events.content AS events_content, events.grounding_metadata AS events_grounding_metadata, events.custom_metadata AS events_custom_metadata, events.usage_metadata AS events_usage_metadata, events.citation_metadata AS events_citation_metadata, events.partial AS events_partial, events.turn_complete AS events_turn_complete, events.error_code AS events_error_code, events.error_message AS events_error_message, events.interrupted AS events_interrupted
FROM events
WHERE events.app_name = %(app_name_1)s AND events.user_id = %(user_id_1)s AND events.session_id = %(session_id_1)s ORDER BY events.timestamp DESC]

@henrywang0314

@henrywang0314 same issue, I had to manually run this migration script if it helps (we're using postgres container)

psql -h postgres -U <username> -d <db_name>

Details

DO $$  
BEGIN  
    -- Add long_running_tool_ids_json column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'long_running_tool_ids_json'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN long_running_tool_ids_json TEXT;  
    END IF;  
  
    -- Add grounding_metadata column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'grounding_metadata'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN grounding_metadata JSONB;  
    END IF;  
  
    -- Add custom_metadata column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'custom_metadata'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN custom_metadata JSONB;  
    END IF;  
  
    -- Add usage_metadata column (CRITICAL - this is causing your error)  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'usage_metadata'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN usage_metadata JSONB;  
    END IF;  
  
    -- Add citation_metadata column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'citation_metadata'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN citation_metadata JSONB;  
    END IF;  
  
    -- Add partial column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'partial'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN partial BOOLEAN;  
    END IF;  
  
    -- Add turn_complete column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'turn_complete'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN turn_complete BOOLEAN;  
    END IF;  
  
    -- Add error_code column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'error_code'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN error_code VARCHAR(256);  
    END IF;  
  
    -- Add error_message column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'error_message'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN error_message VARCHAR(1024);  
    END IF;  
  
    -- Add interrupted column  
    IF NOT EXISTS (  
        SELECT 1  
        FROM information_schema.columns  
        WHERE table_schema = current_schema()  
          AND table_name = 'events'  
          AND column_name = 'interrupted'  
    ) THEN  
        ALTER TABLE events  
            ADD COLUMN interrupted BOOLEAN;  
    END IF;  
END $$;

similar error also occurs when upgrading from release 1.16.0 to 1.17.0 (psycopg2.errors.UndefinedColumn) column events.usage_metadata does not exist LINE 1: ...events.custom_metadata AS events_custom_metadata, events.usa... ^

[SQL: SELECT events.id AS events_id, events.app_name AS events_app_name, events.user_id AS events_user_id, events.session_id AS events_session_id, events.invocation_id AS events_invocation_id, events.author AS events_author, events.actions AS events_actions, events.long_running_tool_ids_json AS events_long_running_tool_ids_json, events.branch AS events_branch, events.timestamp AS events_timestamp, events.content AS events_content, events.grounding_metadata AS events_grounding_metadata, events.custom_metadata AS events_custom_metadata, events.usage_metadata AS events_usage_metadata, events.citation_metadata AS events_citation_metadata, events.partial AS events_partial, events.turn_complete AS events_turn_complete, events.error_code AS events_error_code, events.error_message AS events_error_message, events.interrupted AS events_interrupted FROM events WHERE events.app_name = %(app_name_1)s AND events.user_id = %(user_id_1)s AND events.session_id = %(session_id_1)s ORDER BY events.timestamp DESC]

also getting the same error

same here

Navigation Menu

Repository navigation

Need migration to update Database on new releases #456

Upgrading from v0.1.0 to v0.3.0

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Need migration to update Database on new releases #456

Description

Upgrading from v0.1.0 to v0.3.0

Activity

DeanChensj commented on May 12, 2025

henrywang0314 commented on Oct 23, 2025

luutuankiet commented on Oct 24, 2025

matta-pie commented on Oct 24, 2025

shohei-ihaya commented on Oct 29, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions