fix(sqlalchemy-spanner): handle TOKENLIST and unknown column types in introspection

Spanner full-text search uses TOKENLIST columns, but _type_map does not
include this type and _designate_type() crashes with KeyError on any
unrecognized type string.

This change:
1. Adds TOKENLIST to _type_map, mapped to NullType (it is an
   infrastructure-only type not read/written by applications).
2. Adds a fallback in _designate_type() so unrecognized types return
   NullType with a warning instead of crashing. This future-proofs
   against new Spanner types.

The Go client had the same issue and fixed it in
googleapis/google-cloud-go#11522 (released in spanner v1.78.0).

Fixes #16621

Author: hochoy

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

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import base64
+import warnings
 
 import re
 
@@ -122,6 +123,7 @@ def process(value):
     "TIMESTAMP": types.TIMESTAMP,
     "ARRAY": types.ARRAY,
     "JSON": types.JSON,
+    "TOKENLIST": types.NullType,
 }
 
 
@@ -1226,7 +1228,14 @@ def _designate_type(self, str_repr):
             inner_type = self._designate_type(inner_type_str)
             return _type_map["ARRAY"](inner_type)
         else:
-            return _type_map[str_repr]
+            try:
+                return _type_map[str_repr]
+            except KeyError:
+                warnings.warn(
+                    "Did not recognize Spanner type '%s', "
+                    "mapping it to NullType" % str_repr
+                )
+                return types.NullType()
 
     @engine_to_connection
     def get_multi_indexes(

packages/sqlalchemy-spanner/tests/unit/test_types.py

@@ -0,0 +1,61 @@
+# 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
+#
+#     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.
+
+import warnings
+
+from sqlalchemy import types
+from sqlalchemy.testing.plugin.plugin_base import fixtures
+
+from google.cloud.sqlalchemy_spanner import sqlalchemy_spanner
+
+
+class TestDesignateType(fixtures.TestBase):
+    """Unit tests for SpannerDialect._designate_type."""
+
+    def setup_method(self):
+        self.dialect = sqlalchemy_spanner.SpannerDialect()
+
+    def test_known_types(self):
+        assert isinstance(self.dialect._designate_type("BOOL"), types.Boolean)
+        assert isinstance(self.dialect._designate_type("INT64"), types.BIGINT)
+        assert isinstance(self.dialect._designate_type("FLOAT64"), types.Float)
+        assert isinstance(self.dialect._designate_type("DATE"), types.DATE)
+        assert isinstance(self.dialect._designate_type("TIMESTAMP"), types.TIMESTAMP)
+        assert isinstance(self.dialect._designate_type("JSON"), types.JSON)
+
+    def test_string_with_length(self):
+        result = self.dialect._designate_type("STRING(255)")
+        assert isinstance(result, types.String)
+        assert result.length == 255
+
+    def test_bytes_with_length(self):
+        result = self.dialect._designate_type("BYTES(1024)")
+        assert isinstance(result, types.LargeBinary)
+        assert result.length == 1024
+
+    def test_tokenlist_maps_to_nulltype(self):
+        result = self.dialect._designate_type("TOKENLIST")
+        assert isinstance(result, types.NullType)
+
+    def test_unknown_type_returns_nulltype_with_warning(self):
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            result = self.dialect._designate_type("SOME_FUTURE_TYPE")
+        assert isinstance(result, types.NullType)
+        assert len(caught) == 1
+        assert "SOME_FUTURE_TYPE" in str(caught[0].message)
+
+    def test_array_of_known_type(self):
+        result = self.dialect._designate_type("ARRAY<INT64>")
+        assert isinstance(result, types.ARRAY)