[cofin]

Summary

Adds PKCS#12 (ewallet.p12) to PEM wallet conversion, shared temporary wallet lifecycle management, and tnsnames.ora / sqlnet.ora TNS alias resolution without mutating TNS_ADMIN; adds Oracle Text NEAR((...)) proximity query formatting and exact top-K (FETCH FIRST) fallback in Oracle HNSW and hybrid RRF search builders and ADK memory stores; and adds server-side DBMS_CLOUD.COPY_DATA object-store ingestion to OracleSyncDriver.load_from_storage and OracleAsyncDriver.load_from_storage with automatic HTTP(S) REST URI normalization and client-side Arrow fallback.

Closes #854
Closes #855
Closes #856

Key Changes

Wallet PKCS#12 Conversion, Lifecycle & TNS Alias Resolution (sqlspec/adapters/oracledb/)

• Extend extract_oracle_wallet_zip (sqlspec/adapters/oracledb/core.py) with wallet_password: str | bytes | None = None, pre-extracted wallet directory validation, and PKCS#12 ewallet.p12 -> ewallet.pem (0o600) conversion using optional cryptography PKCS#12 loading.
• Use per-UID deterministic content-hashed temporary wallet directories (0o700, os.lstat symlink and ownership checks, os.O_NOFOLLOW + os.fchmod private writes) with thread-safe reference counting (retain_extracted_wallet_dir, release_extracted_wallet_dir) across OracleSyncConfig, OracleAsyncConfig, and derive_pool clones plus atexit cleanup.
• Add parse_tnsnames_ora and parse_sqlnet_ora in sqlspec/adapters/oracledb/core.py (re-exported in sqlspec/adapters/oracledb/__init__.py) and tns_alias on OracleConnectionParams (sqlspec/adapters/oracledb/config.py) so build_connection_config resolves multi-line TNS aliases and SSL_SERVER_DN_MATCH directly into dsn and connection parameters without mutating os.environ["TNS_ADMIN"].

Hybrid RRF NEAR Proximity Mode & Exact Top-K Fallback (sqlspec/adapters/oracledb/, sqlspec/builder/)

• Extend sanitize_oracle_text_query (sqlspec/adapters/oracledb/core.py) to support operator="NEAR" using functional NEAR(({tok1}, {tok2}, ...)) Oracle Text syntax (falling back to {tok1} for single-token queries).
• Add approximate: bool = True to build_oracle_hnsw_subquery, build_oracle_hybrid_rrf_sql, and build_oracle_hybrid_rrf_query (sqlspec/builder/_vector_distance.py) to toggle between FETCH APPROX FIRST and exact FETCH FIRST vector candidate retrieval.
• Expose keyword-only fts_operator: str = "ACCUM" and approximate: bool = True on OracleAsyncADKMemoryStore.search_entries and OracleSyncADKMemoryStore.search_entries (sqlspec/adapters/oracledb/adk/store.py), forwarding options to hybrid RRF and Oracle Text FTS queries.

Server-Side DBMS_CLOUD.COPY_DATA Ingestion (sqlspec/adapters/oracledb/)

• Add dbms_cloud_credential to OracleDriverFeatures (sqlspec/adapters/oracledb/config.py) and VALID_ORACLE_DRIVER_FEATURE_KEYS (sqlspec/adapters/oracledb/core.py).
• Add resolve_dbms_cloud_source_uri, build_dbms_cloud_format_json, and build_dbms_cloud_copy_data_sql (sqlspec/adapters/oracledb/core.py, with build_dbms_cloud_copy_data_sql re-exported in sqlspec/adapters/oracledb/__init__.py) to normalize s3://, gs:///gcs://, wasbs:///wasb://, and abfss:///abfs:// URIs into DBMS_CLOUD-compatible HTTP(S) REST endpoints and preserve double quotes on case-sensitive or special-character Oracle schema and table identifiers.
• Update OracleSyncDriver.load_from_storage and OracleAsyncDriver.load_from_storage (sqlspec/adapters/oracledb/driver.py) with credential_name and format_options parameters to execute server-side DBMS_CLOUD.COPY_DATA for supported remote formats (parquet, csv, json, jsonl, ndjson), falling back transparently to client-side Arrow ingestion for local paths, uncredentialed loads, unresolvable URIs, or Arrow IPC inputs.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 72.60813% with 209 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.30%. Comparing base (7cd0fb4) to head (9964f96).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
sqlspec/adapters/oracledb/core.py	70.76%	123 Missing and 67 partials ⚠️
sqlspec/adapters/oracledb/adk/store.py	72.22%	10 Missing ⚠️
sqlspec/adapters/oracledb/driver.py	85.00%	2 Missing and 4 partials ⚠️
sqlspec/adapters/oracledb/config.py	91.17%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #858      +/-   ##
==========================================
- Coverage   81.35%   81.30%   -0.05%     
==========================================
  Files         527      527              
  Lines       88242    88851     +609     
  Branches    16436    16576     +140     
==========================================
+ Hits        71788    72241     +453     
- Misses      12058    12162     +104     
- Partials     4396     4448      +52     

Flag	Coverage Δ
integration	59.67% <9.56%> (-0.34%)	⬇️
py3.11	79.73% <72.60%> (-0.05%)	⬇️
py3.12	72.97% <72.60%> (-6.79%)	⬇️
py3.13	79.72% <72.60%> (-0.06%)	⬇️
py3.14	80.67% <72.53%> (-0.05%)	⬇️
unit	73.52% <72.60%> (+<0.01%)	⬆️

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/_vector_distance.py	80.99% <100.00%> (+1.54%)	⬆️
sqlspec/adapters/oracledb/config.py	90.75% <91.17%> (+2.06%)	⬆️
sqlspec/adapters/oracledb/driver.py	76.77% <85.00%> (+0.84%)	⬆️
sqlspec/adapters/oracledb/adk/store.py	64.16% <72.22%> (+0.66%)	⬆️
sqlspec/adapters/oracledb/core.py	73.88% <70.76%> (-2.33%)	⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

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