sqlspec 0.68.0__py3-none-any.whl → 0.69.0__py3-none-any.whl

sqlspec/adapters/oracledb/__init__.py

@@ -17,6 +17,7 @@ from sqlspec.adapters.oracledb.core import (
     OracleTopologyConfig,
     build_arrow_fetch_kwargs,
     build_connection_config,
+    build_dbms_cloud_copy_data_sql,
     build_duality_etag_update_sql,
     build_session_checkout_plsql,
     build_session_context_plsql,
@@ -36,6 +37,8 @@ from sqlspec.adapters.oracledb.core import (
     inject_duality_view_etag,
     oracle_df_batches_to_arrow_reader,
     oracle_df_to_arrow_table,
+    parse_sqlnet_ora,
+    parse_tnsnames_ora,
     sanitize_oracle_text_query,
 )
 from sqlspec.adapters.oracledb.data_dictionary import (
@@ -74,6 +77,7 @@ __all__ = (
     "OracledbSyncDataDictionary",
     "build_arrow_fetch_kwargs",
     "build_connection_config",
+    "build_dbms_cloud_copy_data_sql",
     "build_duality_etag_update_sql",
     "build_session_checkout_plsql",
     "build_session_context_plsql",
@@ -93,5 +97,7 @@ __all__ = (
     "inject_duality_view_etag",
     "oracle_df_batches_to_arrow_reader",
     "oracle_df_to_arrow_table",
+    "parse_sqlnet_ora",
+    "parse_tnsnames_ora",
     "sanitize_oracle_text_query",
 )

sqlspec/adapters/oracledb/adk/store.py

@@ -2382,13 +2382,33 @@ class OracleSyncADKStore(BaseSyncADKStore["OracleSyncConfig"]):
 class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
     """Oracle ADK memory store using async oracledb driver."""
 
-    __slots__ = ("_in_memory",)
+    __slots__ = ("_approximate", "_fts_operator", "_in_memory")
 
     def __init__(self, config: "OracleAsyncConfig") -> None:
         super().__init__(config)
         validate_oracle_identifier(self._memory_table, "table name")
         adk_config = _adk_config(config)
         self._in_memory: bool = bool(adk_config.get("in_memory", False))
+        self._fts_operator: str = str(adk_config.get("fts_operator", "ACCUM"))
+        self._approximate: bool = bool(adk_config.get("approximate", True))
+
+    @property
+    def fts_operator(self) -> str:
+        """Return the default Oracle Text operator for hybrid search."""
+        return self._fts_operator
+
+    @fts_operator.setter
+    def fts_operator(self, value: str) -> None:
+        self._fts_operator = value
+
+    @property
+    def approximate(self) -> bool:
+        """Return whether approximate vector search is enabled."""
+        return self._approximate
+
+    @approximate.setter
+    def approximate(self, value: bool) -> None:
+        self._approximate = bool(value)
 
     async def create_tables(self) -> None:
         if not self.create_schema_enabled:
@@ -2470,10 +2490,19 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
         try:
             if embedding is not None and self._use_fts:
                 return await self._search_entries_hybrid_rrf(
-                    query, embedding, app_name, user_id, effective_limit, scope_filter
+                    query,
+                    embedding,
+                    app_name,
+                    user_id,
+                    effective_limit,
+                    scope_filter,
+                    fts_operator=self._fts_operator,
+                    approximate=self._approximate,
                 )
             if self._use_fts:
-                return await self._search_entries_fts(query, app_name, user_id, effective_limit, scope_filter)
+                return await self._search_entries_fts(
+                    query, app_name, user_id, effective_limit, scope_filter, fts_operator=self._fts_operator
+                )
             return await self._search_entries_simple(query, app_name, user_id, effective_limit, scope_filter)
         except OracleDatabaseError as exc:
             error_obj = exc.args[0] if exc.args else None
@@ -2666,9 +2695,16 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
         return True
 
     async def _search_entries_fts(
-        self, query: str, app_name: str, user_id: str, limit: int, scope_filter: Literal["all", "user", "app"] = "all"
+        self,
+        query: str,
+        app_name: str,
+        user_id: str,
+        limit: int,
+        scope_filter: Literal["all", "user", "app"] = "all",
+        *,
+        fts_operator: str = "ACCUM",
     ) -> "list[StoredMemory]":
-        sanitized_query = sanitize_oracle_text_query(query)
+        sanitized_query = sanitize_oracle_text_query(query, operator=fts_operator)
         if not sanitized_query:
             return []
         where_scope, scope_params = _build_oracle_scope_where(app_name, user_id, scope_filter)
@@ -2705,8 +2741,10 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
         vector_column: str = "embedding",
         rrf_k: int = 60,
         metric: str = "COSINE",
+        fts_operator: str = "ACCUM",
+        approximate: bool = True,
     ) -> "list[StoredMemory]":
-        sanitized_query = sanitize_oracle_text_query(query)
+        sanitized_query = sanitize_oracle_text_query(query, operator=fts_operator)
         where_scope, scope_params = _build_oracle_scope_where(app_name, user_id, scope_filter)
         select_cols = (
             "id",
@@ -2730,6 +2768,7 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
                 vector_param="query_vector",
                 top_k_param="top_k",
                 metric=metric,
+                approximate=approximate,
                 where_clause=where_scope,
             )
             params: dict[str, Any] = {**scope_params, "query_vector": embedding, "top_k": limit}
@@ -2745,6 +2784,7 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
                 top_k_param="top_k",
                 rrf_k_param="rrf_k",
                 metric=metric,
+                approximate=approximate,
                 where_clause=where_scope,
             )
             params = {
@@ -2814,13 +2854,33 @@ class OracleAsyncADKMemoryStore(BaseAsyncADKMemoryStore["OracleAsyncConfig"]):
 class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
     """Oracle ADK memory store using sync oracledb driver."""
 
-    __slots__ = ("_in_memory",)
+    __slots__ = ("_approximate", "_fts_operator", "_in_memory")
 
     def __init__(self, config: "OracleSyncConfig") -> None:
         super().__init__(config)
         validate_oracle_identifier(self._memory_table, "table name")
         adk_config = _adk_config(config)
         self._in_memory = bool(adk_config.get("in_memory", False))
+        self._fts_operator: str = str(adk_config.get("fts_operator", "ACCUM"))
+        self._approximate: bool = bool(adk_config.get("approximate", True))
+
+    @property
+    def fts_operator(self) -> str:
+        """Return the default Oracle Text operator for hybrid search."""
+        return self._fts_operator
+
+    @fts_operator.setter
+    def fts_operator(self, value: str) -> None:
+        self._fts_operator = value
+
+    @property
+    def approximate(self) -> bool:
+        """Return whether approximate vector search is enabled."""
+        return self._approximate
+
+    @approximate.setter
+    def approximate(self, value: bool) -> None:
+        self._approximate = bool(value)
 
     def create_tables(self) -> None:
         """Create the memory table when the data dictionary reports it missing."""
@@ -2904,10 +2964,19 @@ class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
         try:
             if embedding is not None and self._use_fts:
                 return self._search_entries_hybrid_rrf(
-                    query, embedding, app_name, user_id, effective_limit, scope_filter
+                    query,
+                    embedding,
+                    app_name,
+                    user_id,
+                    effective_limit,
+                    scope_filter,
+                    fts_operator=self._fts_operator,
+                    approximate=self._approximate,
                 )
             if self._use_fts:
-                return self._search_entries_fts(query, app_name, user_id, effective_limit, scope_filter)
+                return self._search_entries_fts(
+                    query, app_name, user_id, effective_limit, scope_filter, fts_operator=self._fts_operator
+                )
             return self._search_entries_simple(query, app_name, user_id, effective_limit, scope_filter)
         except OracleDatabaseError as exc:
             error_obj = exc.args[0] if exc.args else None
@@ -3098,9 +3167,16 @@ class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
         return True
 
     def _search_entries_fts(
-        self, query: str, app_name: str, user_id: str, limit: int, scope_filter: Literal["all", "user", "app"] = "all"
+        self,
+        query: str,
+        app_name: str,
+        user_id: str,
+        limit: int,
+        scope_filter: Literal["all", "user", "app"] = "all",
+        *,
+        fts_operator: str = "ACCUM",
     ) -> "list[StoredMemory]":
-        sanitized_query = sanitize_oracle_text_query(query)
+        sanitized_query = sanitize_oracle_text_query(query, operator=fts_operator)
         if not sanitized_query:
             return []
         where_scope, scope_params = _build_oracle_scope_where(app_name, user_id, scope_filter)
@@ -3136,8 +3212,10 @@ class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
         vector_column: str = "embedding",
         rrf_k: int = 60,
         metric: str = "COSINE",
+        fts_operator: str = "ACCUM",
+        approximate: bool = True,
     ) -> "list[StoredMemory]":
-        sanitized_query = sanitize_oracle_text_query(query)
+        sanitized_query = sanitize_oracle_text_query(query, operator=fts_operator)
         where_scope, scope_params = _build_oracle_scope_where(app_name, user_id, scope_filter)
         select_cols = (
             "id",
@@ -3161,6 +3239,7 @@ class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
                 vector_param="query_vector",
                 top_k_param="top_k",
                 metric=metric,
+                approximate=approximate,
                 where_clause=where_scope,
             )
             params: dict[str, Any] = {**scope_params, "query_vector": embedding, "top_k": limit}
@@ -3176,6 +3255,7 @@ class OracleSyncADKMemoryStore(BaseSyncADKMemoryStore["OracleSyncConfig"]):
                 top_k_param="top_k",
                 rrf_k_param="rrf_k",
                 metric=metric,
+                approximate=approximate,
                 where_clause=where_scope,
             )
             params = {

sqlspec/adapters/oracledb/config.py

@@ -1,7 +1,6 @@
 """OracleDB database configuration with direct field-based configuration."""
 
 import contextlib
-import shutil
 from collections.abc import Awaitable, Callable, Mapping
 from inspect import isawaitable
 from pathlib import Path
@@ -38,6 +37,8 @@ from sqlspec.adapters.oracledb.core import (
     execute_session_release_async,
     execute_session_release_sync,
     extract_oracle_wallet_zip,
+    release_extracted_wallet_dir,
+    retain_extracted_wallet_dir,
 )
 from sqlspec.adapters.oracledb.data_dictionary import (
     OracleVersionCache,
@@ -154,6 +155,7 @@ class OracleConnectionParams(TypedDict):
     extra: NotRequired[dict[str, Any]]
     topology: NotRequired[OracleTopologyConfig | dict[str, Any]]
     wallet_zip: NotRequired[str | Path | bytes]
+    tns_alias: NotRequired[str]
 
 
 class OraclePoolParams(OracleConnectionParams):
@@ -240,6 +242,9 @@ class OracleDriverFeatures(TypedDict):
      executemany.
     session_context_hook: Optional declarative session context configuration
      applied on checkout and cleared on release.
+    dbms_cloud_credential: Optional default ``DBMS_CLOUD`` credential name used
+     by ``load_from_storage`` for server-side object-store ingestion via
+     ``DBMS_CLOUD.COPY_DATA``.
     Native pipeline execution is runtime-gated by async Thin-mode driver API support,
      Oracle Database 26ai or newer, and the SQLSPEC_ORACLE_DISABLE_PIPELINE environment
      override; there is no adapter config switch that can force-enable unsupported
@@ -262,6 +267,7 @@ class OracleDriverFeatures(TypedDict):
     enable_direct_path_load: NotRequired[bool]
     session_context_hook: NotRequired[OracleSessionContextConfig | dict[str, Any]]
     enable_session_tracing: NotRequired[bool]
+    dbms_cloud_credential: NotRequired[str | None]
 
 
 class OracleSyncConnectionContext(SyncPoolConnectionContext):
@@ -390,9 +396,15 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
         """
         normalized_conn = dict(normalize_connection_config(connection_config))
         self._extracted_wallet_dir: Path | None = None
+        pending_wallet_dir: Path | None = None
         if normalized_conn.get("wallet_zip") is not None:
-            wallet_dir = extract_oracle_wallet_zip(normalized_conn.pop("wallet_zip"))
-            self._extracted_wallet_dir = wallet_dir
+            raw_wallet_source = normalized_conn.pop("wallet_zip")
+            source_is_existing_dir = isinstance(raw_wallet_source, (str, Path)) and Path(raw_wallet_source).is_dir()
+            wallet_dir = extract_oracle_wallet_zip(
+                raw_wallet_source, wallet_password=normalized_conn.get("wallet_password")
+            )
+            if not source_is_existing_dir or wallet_dir.resolve() != Path(raw_wallet_source).resolve():
+                pending_wallet_dir = wallet_dir
             normalized_conn.setdefault("config_dir", str(wallet_dir))
             normalized_conn.setdefault("wallet_location", str(wallet_dir))
         connection_config = build_connection_config(normalized_conn)
@@ -417,6 +429,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
             extension_config=extension_config,
             **kwargs,
         )
+        if pending_wallet_dir is not None:
+            self._extracted_wallet_dir = pending_wallet_dir
+            retain_extracted_wallet_dir(pending_wallet_dir)
 
     def create_connection(self) -> "OracleSyncConnection":
         """Create a single connection (not from pool).
@@ -466,7 +481,7 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
                 new_driver_features[key] = val
             else:
                 new_conn_cfg[key] = val
-        return type(self)(
+        derived = type(self)(
             connection_config=new_conn_cfg,
             connection_instance=None,
             migration_config=cast("dict[str, Any] | None", dict(self.migration_config))
@@ -480,6 +495,15 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
             else extension_config,
             observability_config=self.observability_config if observability_config is None else observability_config,
         )
+        if (
+            self._extracted_wallet_dir is not None
+            and derived._extracted_wallet_dir is None
+            and str(self._extracted_wallet_dir)
+            in {derived.connection_config.get("config_dir"), derived.connection_config.get("wallet_location")}
+        ):
+            derived._extracted_wallet_dir = self._extracted_wallet_dir
+            retain_extracted_wallet_dir(self._extracted_wallet_dir)
+        return derived
 
     def get_signature_namespace(self) -> "dict[str, Any]":
         """Get the signature namespace for OracleDB types.
@@ -578,7 +602,7 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
         return driver
 
     def _close_pool(self) -> None:
-        """Close the actual connection pool and remove any extracted temporary wallet directory."""
+        """Close the actual connection pool and release any extracted temporary wallet directory."""
         try:
             if self.connection_instance:
                 self.connection_instance.close()
@@ -586,8 +610,9 @@ class OracleSyncConfig(SyncDatabaseConfig[OracleSyncConnection, "OracleSyncConne
             self._oracle_version_cache.reset()
         finally:
             if self._extracted_wallet_dir is not None:
-                shutil.rmtree(self._extracted_wallet_dir, ignore_errors=True)
+                wallet_dir = self._extracted_wallet_dir
                 self._extracted_wallet_dir = None
+                release_extracted_wallet_dir(wallet_dir)
 
 
 class OracleAsyncConnectionContext(AsyncPoolConnectionContext):
@@ -695,9 +720,15 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
         """
         normalized_conn = dict(normalize_connection_config(connection_config))
         self._extracted_wallet_dir: Path | None = None
+        pending_wallet_dir: Path | None = None
         if normalized_conn.get("wallet_zip") is not None:
-            wallet_dir = extract_oracle_wallet_zip(normalized_conn.pop("wallet_zip"))
-            self._extracted_wallet_dir = wallet_dir
+            raw_wallet_source = normalized_conn.pop("wallet_zip")
+            source_is_existing_dir = isinstance(raw_wallet_source, (str, Path)) and Path(raw_wallet_source).is_dir()
+            wallet_dir = extract_oracle_wallet_zip(
+                raw_wallet_source, wallet_password=normalized_conn.get("wallet_password")
+            )
+            if not source_is_existing_dir or wallet_dir.resolve() != Path(raw_wallet_source).resolve():
+                pending_wallet_dir = wallet_dir
             normalized_conn.setdefault("config_dir", str(wallet_dir))
             normalized_conn.setdefault("wallet_location", str(wallet_dir))
         connection_config = build_connection_config(normalized_conn)
@@ -723,6 +754,9 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             extension_config=extension_config,
             **kwargs,
         )
+        if pending_wallet_dir is not None:
+            self._extracted_wallet_dir = pending_wallet_dir
+            retain_extracted_wallet_dir(pending_wallet_dir)
 
     async def create_connection(self) -> OracleAsyncConnection:
         """Create a single async connection (not from pool).
@@ -772,7 +806,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
                 new_driver_features[key] = val
             else:
                 new_conn_cfg[key] = val
-        return type(self)(
+        derived = type(self)(
             connection_config=new_conn_cfg,
             connection_instance=None,
             migration_config=cast("dict[str, Any] | None", dict(self.migration_config))
@@ -786,6 +820,15 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             else extension_config,
             observability_config=self.observability_config if observability_config is None else observability_config,
         )
+        if (
+            self._extracted_wallet_dir is not None
+            and derived._extracted_wallet_dir is None
+            and str(self._extracted_wallet_dir)
+            in {derived.connection_config.get("config_dir"), derived.connection_config.get("wallet_location")}
+        ):
+            derived._extracted_wallet_dir = self._extracted_wallet_dir
+            retain_extracted_wallet_dir(self._extracted_wallet_dir)
+        return derived
 
     def get_signature_namespace(self) -> "dict[str, Any]":
         """Get the signature namespace for OracleAsyncConfig types.
@@ -881,7 +924,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
         return driver
 
     async def _close_pool(self) -> None:
-        """Close the actual async connection pool and remove any extracted temporary wallet directory."""
+        """Close the actual async connection pool and release any extracted temporary wallet directory."""
         try:
             if self.connection_instance:
                 await self.connection_instance.close()
@@ -889,5 +932,6 @@ class OracleAsyncConfig(AsyncDatabaseConfig[OracleAsyncConnection, "OracleAsyncC
             self._oracle_version_cache.reset()
         finally:
             if self._extracted_wallet_dir is not None:
-                shutil.rmtree(self._extracted_wallet_dir, ignore_errors=True)
+                wallet_dir = self._extracted_wallet_dir
                 self._extracted_wallet_dir = None
+                release_extracted_wallet_dir(wallet_dir)