fix(spanner, sqlalchemy-spanner): fix reflection crashes, add native UUID support, and improve JsonObject

packages/google-cloud-spanner/google/cloud/spanner_v1/data_types.py

@@ -57,6 +57,37 @@ def __init__(self, *args, **kwargs):
         if not self._is_null:
             super(JsonObject, self).__init__(*args, **kwargs)
 
+    @property
+    def is_null(self):
+        """Return True if JsonObject represents JSON null."""
+        return self._is_null
+
+    @property
+    def is_array(self):
+        """Return True if JsonObject represents a JSON array."""
+        return self._is_array
+
+    @property
+    def is_scalar(self):
+        """Return True if JsonObject represents a JSON scalar value."""
+        return self._is_scalar_value
+
+    def to_python(self):
+        """Return unwrapped native Python object representation (dict, list, scalar, or None)."""
+        if self._is_null:
+            return None
+        if self._is_array:
+            return [
+                item.to_python() if isinstance(item, JsonObject) else item
+                for item in self._array_value
+            ]
+        if self._is_scalar_value:
+            return self._simple_value
+        return {
+            k: (v.to_python() if isinstance(v, JsonObject) else v)
+            for k, v in self.items()
+        }
+
     def __repr__(self):
         if self._is_array:
             return str(self._array_value)

packages/google-cloud-spanner/tests/unit/test_datatypes.py

@@ -96,3 +96,26 @@ def test_w_JsonObject_of_list_of_simple_JsonData(self):
         expected = json.dumps(data, sort_keys=True, separators=(",", ":"))
         data_jsonobject = JsonObject(JsonObject(data))
         self.assertEqual(data_jsonobject.serialize(), expected)
+
+    def test_to_python_dict(self):
+        obj = JsonObject({"a": 1, "b": [2, 3]})
+        self.assertFalse(obj.is_null)
+        self.assertFalse(obj.is_array)
+        self.assertFalse(obj.is_scalar)
+        self.assertEqual(obj.to_python(), {"a": 1, "b": [2, 3]})
+
+    def test_to_python_array(self):
+        obj = JsonObject([{"a": 1}, 2, "str"])
+        self.assertFalse(obj.is_null)
+        self.assertTrue(obj.is_array)
+        self.assertFalse(obj.is_scalar)
+        self.assertEqual(obj.to_python(), [{"a": 1}, 2, "str"])
+
+    def test_to_python_scalar_and_null(self):
+        scalar_obj = JsonObject("hello")
+        self.assertTrue(scalar_obj.is_scalar)
+        self.assertEqual(scalar_obj.to_python(), "hello")
+
+        null_obj = JsonObject(None)
+        self.assertTrue(null_obj.is_null)
+        self.assertIsNone(null_obj.to_python())

packages/sqlalchemy-spanner/.coveragerc

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[run]
+branch = True
+source =
+    google/cloud/sqlalchemy_spanner
+
+[paths]
+source =
+    google/cloud/sqlalchemy_spanner
+    */site-packages/google/cloud/sqlalchemy_spanner
+
+[report]
+fail_under = 65
+show_missing = True
+exclude_lines =
+    pragma: NO COVER
+    def __repr__
+    raise NotImplementedError
+omit =
+  tests/*
+  */tests/*

packages/sqlalchemy-spanner/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py

@@ -120,6 +120,8 @@ def process(value):
     "TIMESTAMP": types.TIMESTAMP,
     "ARRAY": types.ARRAY,
     "JSON": types.JSON,
+    "TOKENLIST": types.String,
+    "UUID": types.UUID,
 }
 
 
@@ -136,6 +138,7 @@ def process(value):
     types.String: "STRING",
     types.TIME: "TIME",
     types.TIMESTAMP: "TIMESTAMP",
+    types.UUID: "UUID",
     types.Integer: "INT64",
     types.NullType: "INT64",
 }
@@ -426,8 +429,10 @@ def returning_clause(self, stmt, returning_cols, **kw):
             )
             for c in expression._select_iterables(
                 filter(
-                    lambda col: not col.dialect_options.get("spanner", {}).get(
-                        "exclude_from_returning", False
+                    lambda col: (
+                        not col.dialect_options.get("spanner", {}).get(
+                            "exclude_from_returning", False
+                        )
                     ),
                     returning_cols,
                 )
@@ -709,12 +714,16 @@ def visit_create_index(
             options = index.dialect_options["spanner"]
             if "storing" in options:
                 storing = options["storing"]
-                storing_columns = [
-                    index.table.c[col] if isinstance(col, str) else col
-                    for col in storing
-                ]
+                storing_names = []
+                for col in storing:
+                    if isinstance(col, str):
+                        storing_names.append(col)
+                    elif hasattr(col, "name"):
+                        storing_names.append(col.name)
+                    else:
+                        storing_names.append(str(col))
                 text += " STORING (%s)" % ", ".join(
-                    [self.preparer.quote(c.name) for c in storing_columns]
+                    [self.preparer.quote(name) for name in storing_names]
                 )
 
             interleave_in = options.get("interleave_in")
@@ -814,6 +823,12 @@ def visit_NUMERIC(self, type_, **kw):
     def visit_BIGINT(self, type_, **kw):
         return "INT64"
 
+    def visit_UUID(self, type_, **kw):
+        return "UUID"
+
+    def visit_uuid(self, type_, **kw):
+        return "UUID"
+
     def visit_JSON(self, type_, **kw):
         return "JSON"
 
@@ -1300,6 +1315,7 @@ def get_multi_indexes(
                 {table_type_query}
                 {schema_filter_query}
                 i.index_type != 'PRIMARY_KEY'
+                AND i.index_type != 'SEARCH'
                 AND i.spanner_is_managed = FALSE
             GROUP BY i.table_catalog, i.table_schema, i.table_name,
                      i.index_name, i.is_unique
@@ -1324,7 +1340,8 @@ def get_multi_indexes(
                     "column_names": row[3],
                     "unique": row[4],
                     "column_sorting": {
-                        col: order.lower() for col, order in zip(row[3], row[5])
+                        col: (order.lower() if order else None)
+                        for col, order in zip(row[3], row[5] or [])
                     },
                     "include_columns": include_columns if include_columns else [],
                     "dialect_options": dialect_options,

packages/sqlalchemy-spanner/noxfile.py

@@ -85,6 +85,7 @@ class = StreamHandler
 UNIT_TEST_STANDARD_DEPENDENCIES = [
     "mock",
     "pytest",
+    "pytest-cov",
 ]
 
 UNIT_TEST_EXTERNAL_DEPENDENCIES = [
@@ -275,6 +276,9 @@ def mockserver(session):
     session.run(
         "py.test",
         "--quiet",
+        "--cov=google.cloud.sqlalchemy_spanner",
+        "--cov-append",
+        "--cov-config=.coveragerc",
         os.path.join("tests", "mockserver_tests"),
         *session.posargs,
     )
@@ -368,7 +372,15 @@ def unit(session, test_type):
             *UNIT_TEST_DEPENDENCIES,
         )
         session.install(".")
-        session.run("py.test", "--quiet", os.path.join("tests/unit"), *session.posargs)
+        session.run(
+            "py.test",
+            "--quiet",
+            "--cov=google.cloud.sqlalchemy_spanner",
+            "--cov-append",
+            "--cov-config=.coveragerc",
+            os.path.join("tests/unit"),
+            *session.posargs,
+        )
         return
 
 

packages/sqlalchemy-spanner/tests/mockserver_tests/test_dialect_integration.py

@@ -0,0 +1,83 @@
+# Copyright 2026 Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from google.cloud.spanner_admin_database_v1 import UpdateDatabaseDdlRequest
+from google.cloud.spanner_v1 import ResultSet
+from sqlalchemy import Column, Index, MetaData, Table, Uuid, types
+from sqlalchemy.testing import eq_, is_instance_of
+
+from tests.mockserver_tests.mock_server_test_base import (
+    MockServerTestBase,
+    add_result,
+)
+
+
+class TestDialectIntegration(MockServerTestBase):
+    def test_create_table_with_native_uuid(self):
+        """Integration test verifying native UUID and TOKENLIST DDL generation."""
+        add_result(
+            """SELECT true
+FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_SCHEMA="" AND TABLE_NAME="products"
+LIMIT 1
+""",
+            ResultSet(),
+        )
+        engine = self.create_engine()
+        metadata = MetaData()
+        Table(
+            "products",
+            metadata,
+            Column("product_id", Uuid, primary_key=True),
+            Column("token_data", types.String()),
+        )
+        metadata.create_all(engine)
+        requests = self.database_admin_service.requests
+        eq_(1, len(requests))
+        is_instance_of(requests[0], UpdateDatabaseDdlRequest)
+        statement = requests[0].statements[0]
+        assert "product_id UUID NOT NULL" in statement
+
+    def test_create_index_with_storing_clause(self):
+        """Integration test verifying DDL generation for indexes with STORING clause."""
+        add_result(
+            """SELECT true
+FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_SCHEMA="" AND TABLE_NAME="items"
+LIMIT 1
+""",
+            ResultSet(),
+        )
+        engine = self.create_engine()
+        metadata = MetaData()
+        items = Table(
+            "items",
+            metadata,
+            Column("id", Uuid, primary_key=True),
+            Column("category", types.String(50)),
+            Column("name", types.String(100)),
+            Column("description", types.String(500)),
+        )
+        Index(
+            "ix_items_category",
+            items.c.category,
+            spanner_storing=["name", "description"],
+        )
+        metadata.create_all(engine)
+        requests = self.database_admin_service.requests
+        eq_(1, len(requests))
+        is_instance_of(requests[0], UpdateDatabaseDdlRequest)
+        statements = requests[0].statements
+        create_index_statement = [s for s in statements if "CREATE INDEX" in s][0]
+        assert "STORING (name, description)" in create_index_statement