[cofin]

Summary

Adds Oracle enterprise connection topology and in-memory wallet support, declarative session checkout/release context hooks, sub-pool derivation, PyCapsule Arrow batch streaming, HNSW FETCH APPROX FIRST + hybrid RRF vector search, and Oracle 26ai catalog introspection and execution plan diagnostics.

Closes #841
Closes #842
Closes #843
Closes #844
Closes #845
Closes #847

Key Changes

Core & Configuration (sqlspec/config.py, sqlspec/core/explain.py)

• Add DatabaseConfig.derive_pool(**overrides) on SyncDatabaseConfig and AsyncDatabaseConfig to clone pooled adapter configurations with shallow-merged connection_config and driver_features overrides for workload isolation.
• Extend ExplainOptions with display_cursor: bool and xplan_format: str | None for Oracle DBMS_XPLAN.DISPLAY_CURSOR execution plan formatting.

Query Builder (sqlspec/builder/)

• Add Select.vector_top_k(...), build_oracle_vector_top_k(...), and build_oracle_hybrid_rrf_sql(...) supporting Oracle FETCH APPROX FIRST ... ROWS ONLY HNSW index syntax (TARGET ACCURACY) and single-round-trip Reciprocal Rank Fusion (1 / (:k + rank)) across VECTOR_DISTANCE and CONTAINS CTEs.
• Extend build_oracle_explain(...) to support DBMS_XPLAN.DISPLAY_CURSOR(NULL, NULL, format) when display_cursor=True.

Oracle Adapter (sqlspec/adapters/oracledb/)

• Enterprise Topology & In-Memory Wallet (core.py, config.py): Add OracleEndpoint, OracleTopologyConfig, build_tns_description(...) ((ADDRESS_LIST=...) + (CONNECT_DATA=...)), and extract_oracle_wallet_zip(...) with strict 0o700 permissions, zip-slip path validation, and automatic temporary directory cleanup on close_pool().
• Session Context Hooks (core.py, config.py): Add OracleSessionContextConfig and batched anonymous PL/SQL BEGIN ... END; checkout/release callbacks (DBMS_SESSION.SET_IDENTIFIER, DBMS_SESSION.SET_CONTEXT, DBMS_APPLICATION_INFO.SET_MODULE, NLS_* session parameters, EDITION, CURRENT_SCHEMA, and DBMS_SESSION.MODIFY_package_state(DBMS_SESSION.REINITIALIZE)) wired into session_callback.
• Arrow Streaming (core.py, driver.py): Remove unsupported fetch_lobs from get_dataframe_batches kwargs, support arrow_requested_schema, and convert Oracle DataFrame chunks via Arrow PyCapsule (pa.RecordBatch.from_pyarrow(odf)) in select_to_arrow(..., return_format="batches").
• ADK Hybrid Vector + FTS Memory (adk/store.py): Add mode="hybrid" and rrf_k: int = 60 to OracleSyncADKMemoryStore and OracleAsyncADKMemoryStore with automatic fallback when query_embedding is omitted or use_fts is disabled.
• Oracle 26ai Capabilities & Diagnostics (core.py, data_dictionary.py, driver.py):
  • Add sanitize_oracle_text_query(...), JSON Relational Duality View _metadata.etag helpers (extract_duality_view_etag, inject_duality_view_etag, build_duality_etag_update_sql), and VALID_ORACLE_DRIVER_FEATURE_KEYS validation.
  • Add 26ai catalog probes (get_vector_memory_pool, has_cloud_ai, get_apex_release, get_json_duality_views) backed by domain queries in sqlspec/data_dictionary/dialects/oracle/sql/{system,objects,version,views}.sql.
  • Use zero-RTT connection.version inspection in OracleAsyncDriver._pipeline_native_supported and add OracleSyncDriver.explain_statement / OracleAsyncDriver.explain_statement.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 67.16418% with 330 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.37%. Comparing base (dc9ebbe) to head (efbbe30).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
sqlspec/adapters/oracledb/core.py	69.72%	112 Missing and 56 partials ⚠️
sqlspec/adapters/oracledb/data_dictionary.py	39.24%	40 Missing and 8 partials ⚠️
sqlspec/adapters/oracledb/config.py	76.22%	19 Missing and 15 partials ⚠️
sqlspec/config.py	8.10%	34 Missing ⚠️
sqlspec/adapters/oracledb/adk/store.py	60.97%	13 Missing and 3 partials ⚠️
sqlspec/adapters/oracledb/driver.py	74.57%	10 Missing and 5 partials ⚠️
sqlspec/builder/_explain.py	69.23%	5 Missing and 3 partials ⚠️
sqlspec/builder/_vector_distance.py	88.88%	2 Missing and 3 partials ⚠️
sqlspec/builder/_select.py	90.90%	0 Missing and 1 partial ⚠️
sqlspec/core/explain.py	88.88%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #849      +/-   ##
==========================================
- Coverage   81.83%   81.37%   -0.47%     
==========================================
  Files         527      527              
  Lines       86585    87836    +1251     
  Branches    16112    16370     +258     
==========================================
+ Hits        70861    71479     +618     
- Misses      11662    11992     +330     
- Partials     4062     4365     +303     

Flag	Coverage Δ
integration	60.16% <20.89%> (-0.78%)	⬇️
py3.11	79.78% <66.06%> (+20.98%)	⬆️
py3.12	79.79% <66.06%> (-0.14%)	⬇️
py3.13	79.78% <66.06%> (-0.15%)	⬇️
py3.14	80.74% <65.86%> (-0.16%)	⬇️
unit	73.46% <65.27%> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
sqlspec/adapters/oracledb/__init__.py	100.00% <ø> (ø)
sqlspec/builder/__init__.py	80.00% <ø> (ø)
sqlspec/builder/_select.py	69.58% <90.90%> (+0.27%)	⬆️
sqlspec/core/explain.py	97.70% <88.88%> (+0.23%)	⬆️
sqlspec/builder/_vector_distance.py	79.45% <88.88%> (+2.30%)	⬆️
sqlspec/builder/_explain.py	95.11% <69.23%> (-3.39%)	⬇️
sqlspec/adapters/oracledb/driver.py	75.48% <74.57%> (-2.83%)	⬇️
sqlspec/adapters/oracledb/adk/store.py	63.50% <60.97%> (+1.45%)	⬆️
sqlspec/adapters/oracledb/config.py	88.66% <76.22%> (-4.71%)	⬇️
sqlspec/config.py	92.39% <8.10%> (-4.16%)	⬇️
... and 2 more

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.