sqlspec 0.56.0__tar.gz → 0.56.1__tar.gz

{sqlspec-0.56.0 → sqlspec-0.56.1}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.15.22"
+    rev: "v0.16.0"
     hooks:
       - id: ruff
         args: ["--fix"]

{sqlspec-0.56.0 → sqlspec-0.56.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlspec
-Version: 0.56.0
+Version: 0.56.1
 Summary: SQL Experiments in Python
 Project-URL: Discord, https://discord.gg/litestar
 Project-URL: Issue, https://github.com/litestar-org/sqlspec/issues/
@@ -155,14 +155,12 @@ from sqlspec.adapters.sqlite import SqliteConfig
 class Greeting:
     message: str
 
+
 spec = SQLSpec()
 db = spec.add_config(SqliteConfig(connection_config={"database": ":memory:"}))
 
 with spec.provide_session(db) as session:
-    greeting = session.select_one(
-        "SELECT 'Hello, SQLSpec!' AS message",
-        schema_type=Greeting,
-    )
+    greeting = session.select_one("SELECT 'Hello, SQLSpec!' AS message", schema_type=Greeting)
     print(greeting.message)  # Output: Hello, SQLSpec!
 ```
 

{sqlspec-0.56.0 → sqlspec-0.56.1}/README.md

@@ -37,14 +37,12 @@ from sqlspec.adapters.sqlite import SqliteConfig
 class Greeting:
     message: str
 
+
 spec = SQLSpec()
 db = spec.add_config(SqliteConfig(connection_config={"database": ":memory:"}))
 
 with spec.provide_session(db) as session:
-    greeting = session.select_one(
-        "SELECT 'Hello, SQLSpec!' AS message",
-        schema_type=Greeting,
-    )
+    greeting = session.select_one("SELECT 'Hello, SQLSpec!' AS message", schema_type=Greeting)
     print(greeting.message)  # Output: Hello, SQLSpec!
 ```
 

{sqlspec-0.56.0 → sqlspec-0.56.1}/pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.56.0"
+version = "0.56.1"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -308,7 +308,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.56.0"
+current_version = "0.56.1"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

{sqlspec-0.56.0 → sqlspec-0.56.1}/sqlspec/adapters/adbc/core.py

@@ -635,6 +635,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 +875,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 +920,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 +969,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 +978,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 +999,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(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-0.56.0 → sqlspec-0.56.1}/sqlspec/adapters/oracledb/driver.py

@@ -1,7 +1,7 @@
 """Oracle Driver"""
 
 import logging
-from typing import TYPE_CHECKING, Any, NamedTuple, Protocol, cast, overload
+from typing import TYPE_CHECKING, Any, Final, NamedTuple, Protocol, cast, overload
 
 from oracledb import create_pipeline as create_oracle_pipeline
 
@@ -57,6 +57,7 @@ from sqlspec.core import (
     get_cache_config,
     register_driver_profile,
 )
+from sqlspec.core.explain import ORACLE_EXPLAIN_PREFIX, ORACLE_MANAGED_EXPLAIN_META_KEY
 from sqlspec.driver import (
     AsyncDriverAdapterBase,
     AsyncRowStream,
@@ -73,6 +74,7 @@ from sqlspec.utils.logging import get_logger, log_with_context
 from sqlspec.utils.module_loader import ensure_pyarrow
 from sqlspec.utils.text import normalize_identifier, quote_identifier, split_qualified_identifier
 from sqlspec.utils.type_guards import has_pipeline_capability, is_async_readable
+from sqlspec.utils.uuids import uuid4
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -96,6 +98,15 @@ __all__ = (
 
 logger = get_logger(__name__)
 
+PLAN_STATEMENT_ID_MAX_LENGTH: Final[int] = 30
+"""Width of the PLAN_TABLE STATEMENT_ID column."""
+
+PLAN_STATEMENT_ID_PREFIX: Final[str] = "sqlspec_"
+
+PLAN_DISPLAY_SQL: Final[str] = "SELECT plan_table_output FROM TABLE(DBMS_XPLAN.DISPLAY(NULL, :statement_id, 'TYPICAL'))"
+
+PLAN_CLEANUP_SQL: Final[str] = "DELETE FROM plan_table WHERE statement_id = :statement_id"
+
 
 class OraclePipelineDriver(Protocol):
     """Protocol for Oracle pipeline driver methods used in stack execution."""
@@ -368,6 +379,10 @@ class OracleSyncDriver(OraclePipelineMixin, SyncDriverAdapterBase):
         )
         prepared_parameters = cast("list[Any] | tuple[Any, ...] | dict[Any, Any] | None", prepared_parameters)
 
+        explained_sql = _managed_explain_statement(statement, sql)
+        if explained_sql is not None:
+            return self._dispatch_explain_plan(cursor, explained_sql, prepared_parameters)
+
         cursor.execute(sql, prepared_parameters or {}, **build_fetch_kwargs(self.driver_features))
 
         is_select_like = statement.returns_rows() or self._should_force_select(statement, cursor)
@@ -844,6 +859,54 @@ class OracleSyncDriver(OraclePipelineMixin, SyncDriverAdapterBase):
     def _resolve_row_metadata(self, description: Any) -> "tuple[list[str], bool]":
         return resolve_row_metadata(description, self.driver_features, self._row_metadata_cache)
 
+    def _dispatch_explain_plan(self, cursor: Any, explained_sql: str, parameters: Any) -> "ExecutionResult":
+        """Request a plan, read it back, and release the plan table rows.
+
+        Oracle writes the plan to a table instead of returning it, so the plan is
+        tagged with a generated statement id, formatted through ``DBMS_XPLAN``, and
+        deleted again. All three statements run in the caller's transaction, so the
+        plan is read before a rollback can discard it.
+
+        Args:
+            cursor: Oracle cursor object.
+            explained_sql: Statement whose plan is wanted.
+            parameters: Bind values for the explained statement.
+
+        Returns:
+            Execution result carrying the formatted plan rows.
+        """
+        statement_id = _new_plan_statement_id()
+        cursor.execute(_tagged_explain_plan_sql(statement_id, explained_sql), parameters or {})
+
+        try:
+            cursor.execute(PLAN_DISPLAY_SQL, {"statement_id": statement_id}, **build_fetch_kwargs(self.driver_features))
+            fetched_data = cursor.fetchall()
+            column_names, requires_lob_coercion = self._resolve_row_metadata(cursor.description)
+            data, column_names = collect_sync_rows(
+                cast("list[Any] | None", fetched_data),
+                cursor.description,
+                self.driver_features,
+                column_names=column_names,
+                requires_lob_coercion=requires_lob_coercion,
+            )
+            result = self.create_execution_result(
+                cursor,
+                selected_data=data,
+                column_names=column_names,
+                data_row_count=len(data),
+                is_select_result=True,
+                row_format="tuple",
+            )
+        except Exception:
+            try:
+                cursor.execute(PLAN_CLEANUP_SQL, {"statement_id": statement_id})
+            except Exception:
+                logger.warning("Failed to clean up Oracle plan rows after plan retrieval failed", exc_info=True)
+            raise
+        else:
+            cursor.execute(PLAN_CLEANUP_SQL, {"statement_id": statement_id})
+        return result
+
     def _execute_arrow_dataframe(self, sql: str, parameters: "Any", batch_size: int | None) -> "Any":
         """Execute SQL and return an Oracle DataFrame."""
         params = parameters if parameters is not None else []
@@ -1020,6 +1083,10 @@ class OracleAsyncDriver(OraclePipelineMixin, AsyncDriverAdapterBase):
         )
         prepared_parameters = cast("list[Any] | tuple[Any, ...] | dict[Any, Any] | None", prepared_parameters)
 
+        explained_sql = _managed_explain_statement(statement, sql)
+        if explained_sql is not None:
+            return await self._dispatch_explain_plan(cursor, explained_sql, prepared_parameters)
+
         await cursor.execute(sql, prepared_parameters or {}, **build_fetch_kwargs(self.driver_features))
 
         is_select_like = statement.returns_rows() or self._should_force_select(statement, cursor)
@@ -1512,6 +1579,56 @@ class OracleAsyncDriver(OraclePipelineMixin, AsyncDriverAdapterBase):
     def _resolve_row_metadata(self, description: Any) -> "tuple[list[str], bool]":
         return resolve_row_metadata(description, self.driver_features, self._row_metadata_cache)
 
+    async def _dispatch_explain_plan(self, cursor: Any, explained_sql: str, parameters: Any) -> "ExecutionResult":
+        """Request a plan, read it back, and release the plan table rows.
+
+        Oracle writes the plan to a table instead of returning it, so the plan is
+        tagged with a generated statement id, formatted through ``DBMS_XPLAN``, and
+        deleted again. All three statements run in the caller's transaction, so the
+        plan is read before a rollback can discard it.
+
+        Args:
+            cursor: Oracle cursor object.
+            explained_sql: Statement whose plan is wanted.
+            parameters: Bind values for the explained statement.
+
+        Returns:
+            Execution result carrying the formatted plan rows.
+        """
+        statement_id = _new_plan_statement_id()
+        await cursor.execute(_tagged_explain_plan_sql(statement_id, explained_sql), parameters or {})
+
+        try:
+            await cursor.execute(
+                PLAN_DISPLAY_SQL, {"statement_id": statement_id}, **build_fetch_kwargs(self.driver_features)
+            )
+            fetched_data = await cursor.fetchall()
+            column_names, requires_lob_coercion = self._resolve_row_metadata(cursor.description)
+            data, column_names = await collect_async_rows(
+                cast("list[Any] | None", fetched_data),
+                cursor.description,
+                self.driver_features,
+                column_names=column_names,
+                requires_lob_coercion=requires_lob_coercion,
+            )
+            result = self.create_execution_result(
+                cursor,
+                selected_data=data,
+                column_names=column_names,
+                data_row_count=len(data),
+                is_select_result=True,
+                row_format="tuple",
+            )
+        except Exception:
+            try:
+                await cursor.execute(PLAN_CLEANUP_SQL, {"statement_id": statement_id})
+            except Exception:
+                logger.warning("Failed to clean up Oracle plan rows after plan retrieval failed", exc_info=True)
+            raise
+        else:
+            await cursor.execute(PLAN_CLEANUP_SQL, {"statement_id": statement_id})
+        return result
+
     async def _execute_arrow_dataframe(self, sql: str, parameters: "Any", batch_size: int | None) -> "Any":
         """Execute SQL and return an Oracle DataFrame."""
         params = parameters if parameters is not None else []
@@ -1676,6 +1793,57 @@ def _row_has_async_readable(row: Any) -> bool:
     return any(is_async_readable(value) for value in values)
 
 
+def _managed_explain_statement(statement: "SQL", sql: str) -> "str | None":
+    """Extract a SQLSpec-built Oracle plan request without parsing SQL text.
+
+    ``Explain.build()`` marks its SQLGlot command expression. Raw caller SQL has no
+    marker and stays on the ordinary one-statement path. The marked form has one exact
+    generated prefix, so extracting the inner statement is a constant-prefix slice,
+    not a second SQL parse.
+
+    Args:
+        statement: Prepared SQL object.
+        sql: Compiled statement text.
+
+    Returns:
+        The inner statement, or None when SQLSpec does not own the plan flow.
+
+    Raises:
+        SQLSpecError: If a marked statement no longer has SQLSpec's generated shape.
+    """
+    expression = statement.raw_expression
+    if expression is None or not expression.meta.get(ORACLE_MANAGED_EXPLAIN_META_KEY, False):
+        return None
+
+    if not sql.startswith(ORACLE_EXPLAIN_PREFIX) or len(sql) == len(ORACLE_EXPLAIN_PREFIX):
+        msg = "SQLSpec-managed Oracle EXPLAIN statement lost its generated prefix"
+        raise SQLSpecError(msg)
+    return sql[len(ORACLE_EXPLAIN_PREFIX) :]
+
+
+def _new_plan_statement_id() -> str:
+    """Build an identifier that isolates one plan within the session plan table.
+
+    Returns:
+        Identifier of at most ``PLAN_STATEMENT_ID_MAX_LENGTH`` alphanumeric characters.
+    """
+    suffix_length = PLAN_STATEMENT_ID_MAX_LENGTH - len(PLAN_STATEMENT_ID_PREFIX)
+    return f"{PLAN_STATEMENT_ID_PREFIX}{uuid4().hex[:suffix_length]}"
+
+
+def _tagged_explain_plan_sql(statement_id: str, explained_sql: str) -> str:
+    """Rewrite a plan request so its rows can be located and removed again.
+
+    Args:
+        statement_id: Identifier produced by ``_new_plan_statement_id``.
+        explained_sql: Statement whose plan is wanted, with its bind placeholders intact.
+
+    Returns:
+        Plan request tagged with the statement id.
+    """
+    return f"EXPLAIN PLAN SET STATEMENT_ID = '{statement_id}' FOR {explained_sql}"
+
+
 def _retry_arrow_without_fetch_lobs(exc: TypeError, fetch_kwargs: "dict[str, object]") -> "dict[str, object] | None":
     if "fetch_lobs" not in fetch_kwargs or "fetch_lobs" not in str(exc):
         return None