feat(bq-plugin): Reset schema version to 1, default auto_schema_upgrade to True

- _SCHEMA_VERSION starts at "1" (not "3"); future schema changes
  bump 1 → 2 → 3 …
- auto_schema_upgrade now defaults to True because the upgrade is
  additive-only, idempotent, and fail-safe.
- No need to store previous schema versions: the upgrade logic
  diffs actual table columns against the current canonical schema
  and only appends what's missing.
- Added 7 new schema tests: preserves existing columns, handles
  no-label tables, upgrades from older version labels, idempotent
  on second call, verifies update_fields, default config, and
  create_table Conflict handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: caohy1988

src/google/adk/plugins/bigquery_agent_analytics_plugin.py

@@ -70,9 +70,9 @@
     "google.adk.plugins.bigquery_agent_analytics", __version__
 )
 
-# Bumped when the schema changes. Used as a table label for
-# governance and to decide whether auto-upgrade should run.
-_SCHEMA_VERSION = "3"
+# Bumped when the schema changes (1 → 2 → 3 …). Used as a table
+# label for governance and to decide whether auto-upgrade should run.
+_SCHEMA_VERSION = "1"
 _SCHEMA_VERSION_LABEL_KEY = "adk_schema_version"
 
 # Human-in-the-loop (HITL) tool names that receive additional
@@ -493,9 +493,11 @@ class BigQueryLoggerConfig:
   log_session_metadata: bool = True
   # Static custom tags (e.g. {"agent_role": "sales"})
   custom_tags: dict[str, Any] = field(default_factory=dict)
-  # If True, automatically add new columns to existing tables
-  # when the plugin schema evolves. Only additive changes are made.
-  auto_schema_upgrade: bool = False
+  # Automatically add new columns to existing tables when the plugin
+  # schema evolves.  Only additive changes are made (columns are never
+  # dropped or altered).  Safe to leave enabled; a version label on the
+  # table ensures the diff runs at most once per schema version.
+  auto_schema_upgrade: bool = True
 
 
 # ==============================================================================

tests/unittests/plugins/test_bigquery_agent_analytics_plugin.py

@@ -4044,6 +4044,136 @@ def test_upgrade_error_is_logged_not_raised(self):
     # Should not raise
     plugin._ensure_schema_exists()
 
+  def test_upgrade_preserves_existing_columns(self):
+    """Existing columns are never dropped or altered during upgrade."""
+    plugin = self._make_plugin(auto_schema_upgrade=True)
+    # Simulate a table with a subset of canonical columns plus a
+    # user-added custom column that is NOT in the canonical schema.
+    custom_field = bigquery.SchemaField("my_custom_col", "STRING")
+    existing = mock.MagicMock(spec=bigquery.Table)
+    existing.schema = [
+        bigquery.SchemaField("timestamp", "TIMESTAMP"),
+        bigquery.SchemaField("event_type", "STRING"),
+        custom_field,
+    ]
+    existing.labels = {}
+    plugin.client.get_table.return_value = existing
+    plugin._ensure_schema_exists()
+
+    updated_table = plugin.client.update_table.call_args[0][0]
+    updated_names = [f.name for f in updated_table.schema]
+    # Original columns are still present and in original order.
+    assert updated_names[0] == "timestamp"
+    assert updated_names[1] == "event_type"
+    assert updated_names[2] == "my_custom_col"
+    # New canonical columns were appended after existing ones.
+    assert "agent" in updated_names
+    assert "content" in updated_names
+
+  def test_upgrade_from_no_label_treats_as_outdated(self):
+    """A table with no version label is treated as needing upgrade."""
+    plugin = self._make_plugin(auto_schema_upgrade=True)
+    existing = mock.MagicMock(spec=bigquery.Table)
+    existing.schema = list(plugin._schema)  # All columns present
+    existing.labels = {}  # No version label
+    plugin.client.get_table.return_value = existing
+    plugin._ensure_schema_exists()
+
+    # update_table should be called to stamp the version label even
+    # though no new columns were needed.
+    plugin.client.update_table.assert_called_once()
+    updated_table = plugin.client.update_table.call_args[0][0]
+    assert (
+        updated_table.labels[
+            bigquery_agent_analytics_plugin._SCHEMA_VERSION_LABEL_KEY
+        ]
+        == bigquery_agent_analytics_plugin._SCHEMA_VERSION
+    )
+
+  def test_upgrade_from_older_version_label(self):
+    """A table with an older version label triggers upgrade."""
+    plugin = self._make_plugin(auto_schema_upgrade=True)
+    existing = mock.MagicMock(spec=bigquery.Table)
+    existing.schema = [
+        bigquery.SchemaField("timestamp", "TIMESTAMP"),
+        bigquery.SchemaField("event_type", "STRING"),
+    ]
+    # Simulate a table stamped with an older version.
+    existing.labels = {
+        bigquery_agent_analytics_plugin._SCHEMA_VERSION_LABEL_KEY: "0",
+    }
+    plugin.client.get_table.return_value = existing
+    plugin._ensure_schema_exists()
+
+    plugin.client.update_table.assert_called_once()
+    updated_table = plugin.client.update_table.call_args[0][0]
+    # Version label should be updated to current.
+    assert (
+        updated_table.labels[
+            bigquery_agent_analytics_plugin._SCHEMA_VERSION_LABEL_KEY
+        ]
+        == bigquery_agent_analytics_plugin._SCHEMA_VERSION
+    )
+    # Missing columns should have been added.
+    updated_names = {f.name for f in updated_table.schema}
+    assert "agent" in updated_names
+    assert "content" in updated_names
+
+  def test_upgrade_is_idempotent(self):
+    """Calling _ensure_schema_exists twice doesn't double-update."""
+    plugin = self._make_plugin(auto_schema_upgrade=True)
+
+    # First call: table exists with old schema.
+    existing = mock.MagicMock(spec=bigquery.Table)
+    existing.schema = [
+        bigquery.SchemaField("timestamp", "TIMESTAMP"),
+    ]
+    existing.labels = {}
+    plugin.client.get_table.return_value = existing
+    plugin._ensure_schema_exists()
+    assert plugin.client.update_table.call_count == 1
+
+    # Second call: table now has current version label.
+    existing.labels = {
+        bigquery_agent_analytics_plugin._SCHEMA_VERSION_LABEL_KEY: (
+            bigquery_agent_analytics_plugin._SCHEMA_VERSION
+        ),
+    }
+    plugin.client.update_table.reset_mock()
+    plugin._ensure_schema_exists()
+    plugin.client.update_table.assert_not_called()
+
+  def test_update_table_receives_schema_and_labels_fields(self):
+    """update_table is called with update_fields=['schema', 'labels']."""
+    plugin = self._make_plugin(auto_schema_upgrade=True)
+    existing = mock.MagicMock(spec=bigquery.Table)
+    existing.schema = [
+        bigquery.SchemaField("timestamp", "TIMESTAMP"),
+    ]
+    existing.labels = {}
+    plugin.client.get_table.return_value = existing
+    plugin._ensure_schema_exists()
+
+    call_args = plugin.client.update_table.call_args
+    update_fields = call_args[0][1]
+    assert "schema" in update_fields
+    assert "labels" in update_fields
+
+  def test_auto_schema_upgrade_defaults_to_true(self):
+    """Default config has auto_schema_upgrade enabled."""
+    config = bigquery_agent_analytics_plugin.BigQueryLoggerConfig()
+    assert config.auto_schema_upgrade is True
+
+  def test_create_table_conflict_is_ignored(self):
+    """Race condition (Conflict) during create_table is silently handled."""
+    plugin = self._make_plugin()
+    plugin.client.get_table.side_effect = cloud_exceptions.NotFound("not found")
+    plugin.client.create_table.side_effect = cloud_exceptions.Conflict(
+        "already exists"
+    )
+    # Should not raise.
+    plugin._ensure_schema_exists()
+
 
 class TestToolProvenance:
   """Tests for _get_tool_origin helper."""