sqlspec 0.56.0__py3-none-any.whl → 0.56.2__py3-none-any.whl

sqlspec/adapters/adbc/core.py

@@ -46,6 +46,7 @@ from sqlspec.utils.module_loader import import_string
 from sqlspec.utils.serializers import to_json
 from sqlspec.utils.type_converters import build_uuid_coercions
 from sqlspec.utils.type_guards import has_rowcount, has_sqlstate
+from sqlspec.utils.uuids import uuid_from_string
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -635,6 +636,8 @@ _BASE_TYPE_COERCION_MAP: Final[dict[type, Any]] = {
     tuple: _convert_array_for_postgres_adbc,
     list: _convert_array_for_postgres_adbc,
     dict: _identity,
+    UUID: _identity,
+    **build_uuid_coercions(native=True),
 }
 
 
@@ -873,29 +876,27 @@ def prepare_postgres_uuid_bindings(
     if not is_postgres_dialect(dialect):
         return compiled_sql, prepared_parameters
     if is_many:
-        uuid_ordinals = _detect_batch_uuid_ordinals(prepared_parameters)
+        scalar_ordinals, array_ordinals = _detect_batch_uuid_ordinals(prepared_parameters)
     elif isinstance(prepared_parameters, (list, tuple)):
-        uuid_ordinals = tuple(
-            index for index, value in enumerate(prepared_parameters, 1) if isinstance(value, _UUID_TYPES)
-        )
+        scalar_ordinals, array_ordinals = _detect_uuid_ordinals(prepared_parameters)
     else:
-        uuid_ordinals = ()
-    if not uuid_ordinals:
+        scalar_ordinals, array_ordinals = (), ()
+    if not scalar_ordinals and not array_ordinals:
         return compiled_sql, prepared_parameters
     sqlglot_dialect = "postgres" if dialect == "postgresql" else dialect
-    rewritten_sql, effective_ordinals = _rewrite_postgres_uuid_placeholders(
-        compiled_sql, tuple(sorted(uuid_ordinals)), sqlglot_dialect
+    rewritten_sql, effective_scalars, effective_arrays = _rewrite_postgres_uuid_placeholders(
+        compiled_sql, tuple(sorted(scalar_ordinals)), tuple(sorted(array_ordinals)), sqlglot_dialect
     )
-    if not effective_ordinals:
+    if not effective_scalars and not effective_arrays:
         return compiled_sql, prepared_parameters
     if is_many:
         converted_rows = [
-            _convert_uuid_row(row, effective_ordinals, row_number)
+            _convert_uuid_row(row, effective_scalars, effective_arrays, row_number)
             for row_number, row in enumerate(prepared_parameters, 1)
         ]
         converted_parameters = tuple(converted_rows) if isinstance(prepared_parameters, tuple) else converted_rows
     else:
-        converted_parameters = _convert_uuid_row(prepared_parameters, effective_ordinals, 1)
+        converted_parameters = _convert_uuid_row(prepared_parameters, effective_scalars, effective_arrays, 1)
     return rewritten_sql, converted_parameters
 
 
@@ -920,16 +921,42 @@ def _direct_parameter_cast(parameter: exp.Parameter) -> "exp.Cast | None":
     return None
 
 
+def _is_uuid_data_type(target: Any) -> bool:
+    """Report whether a cast target names the scalar ``UUID`` type."""
+    if not isinstance(target, exp.DataType):
+        return False
+    if target.this == exp.DataType.Type.UUID:
+        return True
+    target_kind = target.args.get("kind")
+    if isinstance(target_kind, exp.Dot):
+        target_kind = target_kind.expression
+    return (
+        target.this == exp.DataType.Type.USERDEFINED
+        and isinstance(target_kind, exp.Identifier)
+        and target_kind.name.lower() == "uuid"
+    )
+
+
+def _is_uuid_array_data_type(target: Any) -> bool:
+    """Report whether a cast target names a one-dimensional ``UUID[]`` type."""
+    if not isinstance(target, exp.DataType) or target.this != exp.DataType.Type.ARRAY:
+        return False
+    element_types = target.expressions
+    return len(element_types) == 1 and _is_uuid_data_type(element_types[0])
+
+
 @lru_cache(maxsize=256)
 def _rewrite_postgres_uuid_placeholders(
-    sql: str, uuid_ordinals: "tuple[int, ...]", dialect: str
-) -> "tuple[str, tuple[int, ...]]":
-    """Wrap requested UUID parameter placeholders in explicit UUID casts.
-
-    Placeholders that already carry a different explicit cast stay authoritative
-    and are excluded from the returned effective ordinals. Results are memoized
-    per ``(sql, uuid_ordinals, dialect)`` so repeated executions of the same
-    statement shape reuse the rewrite without parsing again.
+    sql: str, scalar_ordinals: "tuple[int, ...]", array_ordinals: "tuple[int, ...]", dialect: str
+) -> "tuple[str, tuple[int, ...], tuple[int, ...]]":
+    """Wrap requested UUID parameter placeholders in explicit UUID or UUID[] casts.
+
+    Placeholders already carrying the cast their ordinal requires keep that cast
+    and stay effective. Placeholders carrying any other explicit cast stay
+    authoritative and are excluded from the returned effective ordinals. Results
+    are memoized per ``(sql, scalar_ordinals, array_ordinals, dialect)`` so
+    repeated executions of the same statement shape reuse the rewrite without
+    parsing again.
     """
     try:
         expressions = cast(
@@ -943,7 +970,8 @@ def _rewrite_postgres_uuid_placeholders(
         msg = "Failed to parse PostgreSQL ADBC SQL for UUID parameter binding: SQLGlot returned no statements."
         raise SQLSpecError(msg)
 
-    requested = set(uuid_ordinals)
+    array_requested = set(array_ordinals)
+    requested = set(scalar_ordinals) | array_requested
     authoritative: set[int] = set()
     for expression in expressions:
         for parameter in expression.find_all(exp.Parameter):
@@ -951,23 +979,18 @@ def _rewrite_postgres_uuid_placeholders(
             if ordinal is None or ordinal not in requested:
                 continue
             cast_expression = _direct_parameter_cast(parameter)
-            if cast_expression is not None:
-                target = cast_expression.args.get("to")
-                target_kind = target.args.get("kind") if isinstance(target, exp.DataType) else None
-                if isinstance(target_kind, exp.Dot):
-                    target_kind = target_kind.expression
-                is_uuid_cast = isinstance(target, exp.DataType) and (
-                    target.this == exp.DataType.Type.UUID
-                    or (
-                        target.this == exp.DataType.Type.USERDEFINED
-                        and isinstance(target_kind, exp.Identifier)
-                        and target_kind.name.lower() == "uuid"
-                    )
-                )
-                if not is_uuid_cast:
-                    authoritative.add(ordinal)
-    effective = tuple(ordinal for ordinal in uuid_ordinals if ordinal not in authoritative)
-    effective_set = set(effective)
+            if cast_expression is None:
+                continue
+            target = cast_expression.args.get("to")
+            matches_required_cast = (
+                _is_uuid_array_data_type(target) if ordinal in array_requested else _is_uuid_data_type(target)
+            )
+            if not matches_required_cast:
+                authoritative.add(ordinal)
+    effective_scalars = tuple(ordinal for ordinal in scalar_ordinals if ordinal not in authoritative)
+    effective_arrays = tuple(ordinal for ordinal in array_ordinals if ordinal not in authoritative)
+    effective_array_set = set(effective_arrays)
+    effective_set = set(effective_scalars) | effective_array_set
 
     def wrap_parameter(node: exp.Expression) -> exp.Expression:
         if not isinstance(node, exp.Parameter):
@@ -977,52 +1000,112 @@ def _rewrite_postgres_uuid_placeholders(
             return node
         if _direct_parameter_cast(node) is not None:
             return node
-        return exp.Cast(this=node.copy(), to=exp.DataType.build("UUID"))
+        target_type = "UUID[]" if ordinal in effective_array_set else "UUID"
+        return exp.Cast(this=node.copy(), to=exp.DataType.build(target_type, dialect=dialect))
 
     for expression in expressions:
         expression.transform(wrap_parameter, copy=False)
-    return "; ".join(expression.sql(dialect=dialect) for expression in expressions), effective
+    rewritten = "; ".join(expression.sql(dialect=dialect) for expression in expressions)
+    return rewritten, effective_scalars, effective_arrays
+
+
+def _sequence_holds_uuid(values: "list[Any] | tuple[Any, ...]") -> bool:
+    """Report whether a sequence's first non-null element is a UUID."""
+    for value in values:
+        if value is not None:
+            return isinstance(value, _UUID_TYPES)
+    return False
 
 
-def _detect_batch_uuid_ordinals(parameters: Any) -> "tuple[int, ...]":
+def _detect_uuid_ordinals(parameters: "list[Any] | tuple[Any, ...]") -> "tuple[tuple[int, ...], tuple[int, ...]]":
+    """Split a parameter sequence into scalar-UUID and UUID-array ordinals."""
+    scalar_ordinals: list[int] = []
+    array_ordinals: list[int] = []
+    for ordinal, value in enumerate(parameters, 1):
+        if isinstance(value, _UUID_TYPES):
+            scalar_ordinals.append(ordinal)
+        elif isinstance(value, (list, tuple)) and _sequence_holds_uuid(value):
+            array_ordinals.append(ordinal)
+    return tuple(scalar_ordinals), tuple(array_ordinals)
+
+
+def _detect_batch_uuid_ordinals(parameters: Any) -> "tuple[tuple[int, ...], tuple[int, ...]]":
     if not isinstance(parameters, (list, tuple)) or not parameters:
-        return ()
+        return (), ()
     first_row = parameters[0]
     if not isinstance(first_row, (list, tuple)):
-        return ()
+        return (), ()
     expected_size = len(first_row)
     for row in parameters:
         if not isinstance(row, (list, tuple)) or len(row) != expected_size:
-            return ()
-    return tuple(
-        ordinal
-        for ordinal in range(1, expected_size + 1)
-        if any(isinstance(row[ordinal - 1], _UUID_TYPES) for row in parameters)
+            return (), ()
+    scalar_ordinals: list[int] = []
+    array_ordinals: list[int] = []
+    for ordinal in range(1, expected_size + 1):
+        values = [row[ordinal - 1] for row in parameters]
+        if any(isinstance(value, _UUID_TYPES) for value in values):
+            scalar_ordinals.append(ordinal)
+        elif any(isinstance(value, (list, tuple)) and _sequence_holds_uuid(value) for value in values):
+            array_ordinals.append(ordinal)
+    return tuple(scalar_ordinals), tuple(array_ordinals)
+
+
+def _uuid_binding_error(ordinal: int, value: Any, row_number: int, element_index: "int | None" = None) -> str:
+    """Build the incompatible-value message for a UUID parameter ordinal."""
+    location = "" if element_index is None else f" at element {element_index}"
+    return (
+        f"ADBC PostgreSQL UUID parameter ordinal {ordinal} has incompatible "
+        f"{type(value).__name__} value{location} in batch row {row_number}; expected a UUID object, "
+        "parseable UUID string, or None."
+    )
+
+
+def _convert_uuid_value(value: Any, ordinal: int, row_number: int, element_index: "int | None" = None) -> Any:
+    """Normalize one UUID-bound value to its canonical string form."""
+    if value is None:
+        return None
+    if isinstance(value, _UUID_TYPES):
+        return str(value)
+    if not isinstance(value, str):
+        raise SQLSpecError(_uuid_binding_error(ordinal, value, row_number, element_index))
+    try:
+        return str(uuid_from_string(value))
+    except (TypeError, ValueError) as exc:
+        raise SQLSpecError(_uuid_binding_error(ordinal, value, row_number, element_index)) from exc
+
+
+def _null_array_element_error(ordinal: int, row_number: int, element_index: int) -> str:
+    """Build the null-array-element message for a UUID array parameter ordinal."""
+    return (
+        f"ADBC PostgreSQL UUID parameter ordinal {ordinal} has a null value at element {element_index} "
+        f"in batch row {row_number}; the PostgreSQL ADBC driver encodes null array elements as empty "
+        "strings, which PostgreSQL rejects for UUID[]. Remove the null element or bind the array as text."
     )
 
 
-def _convert_uuid_row(row: Any, ordinals: "tuple[int, ...]", row_number: int) -> Any:
+def _convert_uuid_sequence(values: Any, ordinal: int, row_number: int) -> "list[Any]":
+    """Normalize every element of a UUID array parameter."""
+    converted: list[Any] = []
+    for element_index, value in enumerate(values, 1):
+        if value is None:
+            raise SQLSpecError(_null_array_element_error(ordinal, row_number, element_index))
+        converted.append(_convert_uuid_value(value, ordinal, row_number, element_index))
+    return converted
+
+
+def _convert_uuid_row(
+    row: Any, scalar_ordinals: "tuple[int, ...]", array_ordinals: "tuple[int, ...]", row_number: int
+) -> Any:
     converted = list(row)
-    for ordinal in ordinals:
+    for ordinal in scalar_ordinals:
+        converted[ordinal - 1] = _convert_uuid_value(converted[ordinal - 1], ordinal, row_number)
+    for ordinal in array_ordinals:
         value = converted[ordinal - 1]
         if value is None:
             continue
-        if not isinstance(value, _UUID_TYPES) and not isinstance(value, str):
-            msg = (
-                f"ADBC PostgreSQL UUID parameter ordinal {ordinal} has incompatible "
-                f"{type(value).__name__} value in batch row {row_number}; expected a UUID object, "
-                "parseable UUID string, or None."
-            )
-            raise SQLSpecError(msg)
-        try:
-            converted[ordinal - 1] = str(UUID(str(value)))
-        except (AttributeError, TypeError, ValueError) as exc:
-            msg = (
-                f"ADBC PostgreSQL UUID parameter ordinal {ordinal} has incompatible "
-                f"{type(value).__name__} value in batch row {row_number}; expected a UUID object, "
-                "parseable UUID string, or None."
-            )
-            raise SQLSpecError(msg) from exc
+        if not isinstance(value, (list, tuple)):
+            raise SQLSpecError(_uuid_binding_error(ordinal, value, row_number))
+        converted[ordinal - 1] = _convert_uuid_sequence(value, ordinal, row_number)
     return tuple(converted) if isinstance(row, tuple) else converted
 
 

sqlspec/adapters/adbc/driver.py

@@ -40,7 +40,7 @@ from sqlspec.core import (
 )
 from sqlspec.driver import BaseSyncExceptionHandler, SyncDriverAdapterBase, SyncRowStream
 from sqlspec.exceptions import DatabaseConnectionError, SQLSpecError
-from sqlspec.utils.arrow_helpers import arrow_reader_with_deferred_close
+from sqlspec.utils.arrow_helpers import arrow_reader_with_deferred_close, arrow_table_to_pylist
 from sqlspec.utils.logging import get_logger
 from sqlspec.utils.module_loader import ensure_pyarrow
 from sqlspec.utils.serializers import to_json
@@ -129,7 +129,12 @@ class AdbcSelectStreamSource:
                 batch = next(reader)
             except StopIteration:
                 return []
-            rows = cast("list[dict[str, Any]]", batch.to_pylist())
+            rows = arrow_table_to_pylist(
+                batch,
+                decode_arrow_extension_types=bool(
+                    self._driver.driver_features.get("enable_arrow_extension_types", True)
+                ),
+            )
             if rows:
                 return rows
 
@@ -224,7 +229,10 @@ class AdbcDriver(SyncDriverAdapterBase):
 
         if is_select_like:
             arrow_table = cursor.fetch_arrow_table()
-            data = arrow_table.to_pylist()
+            data = arrow_table_to_pylist(
+                arrow_table,
+                decode_arrow_extension_types=bool(self.driver_features.get("enable_arrow_extension_types", True)),
+            )
             column_names = list(arrow_table.column_names)
             return self.create_execution_result(
                 cursor,

sqlspec/adapters/bigquery/driver.py

@@ -772,14 +772,33 @@ def _bigquery_arrow_reader_from_iterable(batches: "Iterable[ArrowRecordBatch]")
 def _records_to_json_rows(
     records: "Sequence[Mapping[str, Any]] | Sequence[Sequence[Any]]", columns: "list[str] | None"
 ) -> "list[dict[str, Any]]":
-    materialized = list(records)
+    materialized = records if isinstance(records, list) else list(records)
     if not materialized:
         msg = "load_from_records requires at least one record."
         raise ImproperConfigurationError(msg)
 
     first = materialized[0]
     if isinstance(first, Mapping):
-        resolved = columns if columns is not None else list(first.keys())
+        if columns is None:
+            resolved = list(first.keys())
+            expected = set(resolved)
+            can_reuse = True
+            for record in materialized:
+                if not isinstance(record, Mapping):
+                    msg = "load_from_records mapping records must all be mappings."
+                    raise ImproperConfigurationError(msg)
+                record_keys = list(record.keys())
+                if set(record_keys) != expected:
+                    msg = "load_from_records mapping records must all share the same keys."
+                    raise ImproperConfigurationError(msg)
+                if type(record) is not dict or record_keys != resolved:
+                    can_reuse = False
+            validated_records = cast("list[Mapping[str, Any]]", materialized)
+            if can_reuse:
+                return cast("list[dict[str, Any]]", validated_records)
+            return [{column: record[column] for column in resolved} for record in validated_records]
+
+        resolved = columns
         expected = set(resolved)
         rows: list[dict[str, Any]] = []
         for record in materialized:

sqlspec/adapters/duckdb/core.py

@@ -4,7 +4,6 @@ import contextlib
 from datetime import date, datetime
 from decimal import Decimal
 from typing import TYPE_CHECKING, Any, Final, cast
-from uuid import UUID
 
 from sqlspec.core import DriverParameterProfile, ParameterStyle, StatementConfig, build_statement_config_from_profile
 from sqlspec.exceptions import (
@@ -24,6 +23,7 @@ from sqlspec.exceptions import (
 from sqlspec.utils.serializers import to_json
 from sqlspec.utils.type_converters import build_decimal_converter, build_uuid_coercions, time_iso_convert
 from sqlspec.utils.type_guards import has_rowcount
+from sqlspec.utils.uuids import uuid_from_string
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
@@ -395,7 +395,7 @@ def _restore_uuid_columns(rows: "list[dict[str, Any]]", description: "list[Any]
         for column in uuid_columns:
             value = row.get(column)
             if isinstance(value, str):
-                row[column] = UUID(value)
+                row[column] = uuid_from_string(value)
 
 
 driver_profile = build_profile()

sqlspec/adapters/oracledb/_json_handlers.py

@@ -6,8 +6,9 @@ and Oracle's JSON storage types via connection type handlers.
 Routing matrix (input):
 
 * Oracle 21c+ native ``JSON``: bind via ``DB_TYPE_JSON`` (binary OSON).
-* Oracle 12c-20c with ``BLOB CHECK (... IS JSON)``: bind via ``DB_TYPE_BLOB`` with
- textual UTF-8 JSON bytes.
+* Oracle 12c-20c with ``BLOB CHECK (... IS JSON)``: the driver pre-serializes
+  JSON-shaped values and creates a ``DB_TYPE_BLOB`` locator containing UTF-8
+  JSON before input-handler dispatch.
 * Oracle 11g and earlier: bind via ``DB_TYPE_CLOB`` with serialized JSON string.
 * The rung is chosen by ``resolve_oracle_json_storage``, the single JSON-threshold
  source shared with ``OracleVersionInfo`` and the extension stores.
@@ -33,11 +34,12 @@ handler returns ``None`` for values it does not own.
 """
 
 from functools import partial
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 from oracledb import DB_TYPE_CHAR, DB_TYPE_NCHAR, DB_TYPE_NVARCHAR, DB_TYPE_VARCHAR
 
 from sqlspec.adapters.oracledb._typing import DB_TYPE_BLOB, DB_TYPE_CLOB, DB_TYPE_JSON, DB_TYPE_LONG, DB_TYPE_LONG_RAW
+from sqlspec.adapters.oracledb.data_dictionary import resolve_oracle_connection_major
 from sqlspec.data_dictionary.dialects.oracle import (
     ORACLE_JSON_STORAGE_BLOB_JSON,
     ORACLE_JSON_STORAGE_NATIVE,
@@ -51,6 +53,7 @@ if TYPE_CHECKING:
 __all__ = (
     "chain_input_handler",
     "chain_output_handler",
+    "is_json_payload",
     "json_converter_in_blob",
     "json_converter_in_clob",
     "json_converter_out_blob",
@@ -131,7 +134,7 @@ def chain_input_handler(inner: Any, fallback: "Any | None") -> Any:
     instance: python-oracledb selects its calling convention via
     ``inspect.signature(handler)``, which succeeds for a partial of a (compiled)
     function but raises ``ValueError`` for a compiled ``__call__`` object -- the
-    latter forces the legacy 6-argument call and breaks fetches.
+    latter forces the older 6-argument call and breaks fetches.
     """
     return partial(_chained_input_handler, inner, fallback)
 
@@ -144,7 +147,7 @@ def chain_output_handler(inner: Any, fallback: "Any | None") -> Any:
     return partial(_chained_output_handler, inner, fallback)
 
 
-def _is_json_payload(value: Any) -> bool:
+def is_json_payload(value: Any) -> bool:
     """Return True if the value should be claimed by the JSON input handler.
 
     ``dict`` and ``tuple``/``list`` of dicts are claimed. Sequences whose first
@@ -167,10 +170,10 @@ def _is_json_payload(value: Any) -> bool:
 
 def _input_type_handler(cursor: "Cursor | AsyncCursor", value: Any, arraysize: int) -> Any:
     """Oracle input type handler for JSON-shaped Python values."""
-    if not _is_json_payload(value):
+    if not is_json_payload(value):
         return None
 
-    server_major = cast("int | None", getattr(cursor.connection, "_sqlspec_oracle_major", None))
+    server_major = resolve_oracle_connection_major(cursor.connection)
 
     if server_major is None:
         return cursor.var(DB_TYPE_JSON, arraysize=arraysize)

sqlspec/adapters/oracledb/_param_types.py

@@ -8,7 +8,8 @@ Wrap a parameter value to express explicit intent:
 
 * :class:`OracleClob` — bind as ``DB_TYPE_CLOB`` regardless of length.
 * :class:`OracleBlob` — bind as ``DB_TYPE_BLOB`` regardless of length.
-* :class:`OracleJson` — bind as native JSON; defers to the C1 input handler.
+* :class:`OracleJson` — express JSON intent; the input handler selects the
+  storage type supported by the connected Oracle version.
 
 The wrappers themselves perform no validation — type discipline lives at the
 routing site so error messages can include database-context detail.
@@ -38,7 +39,7 @@ class OracleBlob:
 
 
 class OracleJson:
-    """Mark a value to be bound as native ``DB_TYPE_JSON`` regardless of detected version."""
+    """Mark a value for version-aware Oracle JSON binding."""
 
     __slots__ = ("value",)
 

sqlspec/adapters/oracledb/_uuid_handlers.py

@@ -10,6 +10,7 @@ from typing import TYPE_CHECKING, Any
 from sqlspec.adapters.oracledb._json_handlers import chain_input_handler, chain_output_handler
 from sqlspec.adapters.oracledb._typing import DB_TYPE_RAW
 from sqlspec.utils.logging import get_logger
+from sqlspec.utils.uuids import uuid_from_bytes
 
 if TYPE_CHECKING:
     from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
@@ -59,7 +60,7 @@ def uuid_converter_out(value: bytes | None) -> "uuid.UUID | bytes | None":
         return value
 
     try:
-        return uuid.UUID(bytes=value)
+        return uuid_from_bytes(value)
     except (ValueError, TypeError):
         logger.debug("RAW(16) value is not valid UUID format, returning as bytes", extra={"value_length": len(value)})
         return value

sqlspec/adapters/oracledb/adk/store.py

@@ -296,7 +296,7 @@ class OracleAsyncADKStore(BaseAsyncADKStore["OracleAsyncConfig"]):
         config: OracleAsyncConfig with extension_config["adk"] settings.
 
     Notes:
-        - JSON storage type detected based on Oracle version (21c+, 12c+, legacy)
+        - JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
         - event_data stored as JSON (21c+) or BLOB (older versions)
         - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
         - Named parameters using :param_name
@@ -1265,7 +1265,7 @@ class OracleSyncADKStore(BaseSyncADKStore["OracleSyncConfig"]):
         config: OracleSyncConfig with extension_config["adk"] settings.
 
     Notes:
-        - JSON storage type detected based on Oracle version (21c+, 12c+, legacy)
+        - JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
         - event_data stored as JSON (21c+) or BLOB (older versions)
         - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
         - Named parameters using :param_name

sqlspec/adapters/oracledb/config.py

@@ -23,7 +23,7 @@ from sqlspec.adapters.oracledb._typing import (
 from sqlspec.adapters.oracledb._uuid_handlers import register_uuid_handlers
 from sqlspec.adapters.oracledb._vector_handlers import register_numpy_handlers  # pyright: ignore[reportPrivateUsage]
 from sqlspec.adapters.oracledb.core import apply_driver_features, default_statement_config
-from sqlspec.adapters.oracledb.data_dictionary import OracleVersionCache
+from sqlspec.adapters.oracledb.data_dictionary import OracleVersionCache, resolve_oracle_connection_major
 from sqlspec.adapters.oracledb.driver import (
     OracleAsyncDriver,
     OracleAsyncExceptionHandler,
@@ -32,7 +32,6 @@ from sqlspec.adapters.oracledb.driver import (
 )
 from sqlspec.adapters.oracledb.migrations import OracleAsyncMigrationTracker, OracleSyncMigrationTracker
 from sqlspec.config import AsyncDatabaseConfig, ExtensionConfigs, SyncDatabaseConfig
-from sqlspec.data_dictionary.dialects.oracle import parse_oracle_version_components
 from sqlspec.driver._async import AsyncPoolConnectionContext, AsyncPoolSessionFactory
 from sqlspec.driver._sync import SyncPoolConnectionContext, SyncPoolSessionFactory
 from sqlspec.extensions.events import EventRuntimeHints
@@ -413,9 +412,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
         vector case) internally. UUID registration remains gated for
         backwards compatibility with existing user configurations.
 
-        Caches ``connection._sqlspec_oracle_major`` so the JSON input handler
-        can pick the right binding path (``DB_TYPE_JSON`` on 21c+, OSON-encoded
-        ``DB_TYPE_BLOB`` on 19c-20c, JSON-string ``DB_TYPE_CLOB`` on 12c-18c)
+        Caches ``connection._sqlspec_oracle_major`` so JSON parameter coercion
+        can pick the right binding path (``DB_TYPE_JSON`` on 21c+, a textual
+        ``BLOB IS JSON`` locator on 12c-20c, and ``DB_TYPE_CLOB`` before 12c)
         without re-querying server metadata on every bind. Caches
         ``connection._sqlspec_vector_return_format`` so the vector output
         handler can dispatch to ``numpy`` / ``list`` / ``array`` without
@@ -434,7 +433,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
 
         # Stash detected major version on the connection so the JSON input handler
         # can pick the right binding path without per-bind metadata queries.
-        setattr(connection, "_sqlspec_oracle_major", _resolve_connection_major(self._oracle_version_cache, connection))
+        setattr(
+            connection, "_sqlspec_oracle_major", resolve_oracle_connection_major(connection, self._oracle_version_cache)
+        )
         # Stash the vector-read format so the VECTOR output handler can
         # dispatch without re-reading driver-feature defaults on every fetch.
         setattr(connection, "_sqlspec_vector_return_format", self.driver_features.get("vector_return_format"))
@@ -628,7 +629,9 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
 
         # Stash detected major version on the connection so the JSON input handler
         # can pick the right binding path without per-bind metadata queries.
-        setattr(connection, "_sqlspec_oracle_major", _resolve_connection_major(self._oracle_version_cache, connection))
+        setattr(
+            connection, "_sqlspec_oracle_major", resolve_oracle_connection_major(connection, self._oracle_version_cache)
+        )
         # Stash the vector-read format so the VECTOR output handler can
         # dispatch without re-reading driver-feature defaults on every fetch.
         setattr(connection, "_sqlspec_vector_return_format", self.driver_features.get("vector_return_format"))
@@ -655,24 +658,3 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             await self.connection_instance.close()
             self.connection_instance = None
         self._oracle_version_cache.reset()
-
-
-def _resolve_connection_major(cache: "OracleVersionCache", connection: Any) -> "int | None":
-    """Resolve the Oracle server major for connection-setup type handlers.
-
-    Prefers the pool-scoped version cache once a driver has resolved it through
-    the data-dictionary path. Before that, the major is parsed from
-    ``connection.version`` — a connection attribute populated at connect time, so
-    no query is issued — using the same version parser the data dictionary uses.
-    Returns ``None`` when unavailable; callers treat ``None`` as "assume 21c+".
-    """
-    if cache.resolved and cache.version is not None:
-        return cache.version.major
-    try:
-        version_str = connection.version
-    except AttributeError:
-        return None
-    if not version_str:
-        return None
-    components = parse_oracle_version_components(str(version_str))
-    return components[0] if components is not None else None