Diogovieir/oracledb

[diogovieir]

What’s new

This PR adds first-class support for Oracle 23c/23ai AI Vector Search to PureCPP, standing side-by-side with the existing Redis backend.

• components/VectorDatabase/src/backends/oracle_backend.cpp – full HNSW implementation using the native VECTOR(...) datatype and DBMS_VECTOR package.

  • Automatic schema bootstrap (CREATE TABLE … VECTOR, DBMS_VECTOR.CREATE_INDEX).

  • Supports COSINE, L2, and IP distance metrics.

• CMake integration

  • New option VDB_WITH_ORACLE (ON by default).

  • Fetches and builds ODPI-C and links against Oracle Instant Client (libclntsh).

  • target_compile_definitions(DPI_CPP_WRAPPER_FOUND) lets the code know when the real ODPI-C headers are present; otherwise a tiny stub is compiled so the whole project still builds without Oracle.

• Python bindings

  • vectorDB.list_backends() now shows ["oracle", "redis"].

  • Usage from Python is identical to Redis – see example below.

---

🔧 Building the Oracle backend

1. Install Instant Client (one–liner)

   bash
   CopyEdit
   ./scripts/fetch_instant_client.sh   # downloads & unpacks 23.4 basiclite+sdk under /opt/oracle
   sudo ldconfig                       # registers libclntsh
   

   Manual install? Follow Oracle’s Instant Client docs. Make sure libclntsh.so is reachable either via LD_LIBRARY_PATH or /etc/ld.so.conf.d/oracle-instantclient.conf.

2. Configure & build

   bash
   CopyEdit
   mkdir -B build && cd build
   cmake .. -DVDB_WITH_ORACLE=ON       # OFF if you want to skip Oracle
   cmake --build . -j$(nproc) --target RagPUREAI
   

3. Verify

   bash
   CopyEdit
   export PYTHONPATH="$PWD:$PYTHONPATH"
   python - <<'PY'
   import RagPUREAI
   print(RagPUREAI.vectorDB.list_backends())   # ➜ ['oracle', 'redis']
   PY
   

---

🐍 Python quick-start

python
CopyEdit
import json, numpy as np
from RagPUREAI import RAGDocument
from RagPUREAI.vectorDB import make_backend
cfg = {

"user":           "demo",

"password":       "demo_pw",

"connect_string": "localhost/freepdb1",   # EZ-connect, TNS or wallet

"dim":            1536,

"metric":         "COSINE"                # or "L2" / "IP"

}
db = make_backend("oracle", json.dumps(cfg))

assert db.is_open()
docs = [

RAGDocument({"id": "1"}, "hello oracle", np.random.rand(1536).tolist()),

RAGDocument({"id": "2"}, "another row",  np.random.rand(1536).tolist()),

]

db.insert(docs)
qvec = np.random.rand(1536).tolist()

for rank, r in enumerate(db.query(qvec, k=2), 1):

print(rank, r.score, r.doc.page_content, r.doc.metadata)

db.close()

---

📂 Files touched

Path	Purpose
components/VectorDatabase/src/backends/oracle_backend.cpp	New backend
components/VectorDatabase/include/odpi.hpp	Thin wrapper / stub forwarder
CMakeLists.txt	VDB_WITH_ORACLE, ODPI-C fetch, Instant Client detection, rpath
components/VectorDatabase/python/binding_vectordb.cpp	force_link_oracle_backend()
scripts/fetch_instant_client.sh	Convenience installer

---

📝 Notes & caveats

• Requires Oracle 23c/23ai or Autonomous DB with the AI Vector feature.

• The build script looks for Instant Client 23.4 under /opt/oracle/instantclient_23_4; adjust OCI_LIB and OCI_INCLUDE_DIR in CMakeLists.txt if you keep it elsewhere.

• If you disable Oracle (-DVDB_WITH_ORACLE=OFF) the stub kicks in so CI pipelines without Instant Client still build PureCPP.

Happy vector-searching! 🎉

What’s new

This PR adds first-class support for Oracle 23c/23ai AI Vector Search to PureCPP, standing side-by-side with the existing Redis backend.

components/VectorDatabase/src/backends/oracle_backend.cpp – full HNSW implementation using the native VECTOR(...) datatype and DBMS_VECTOR package.
Automatic schema bootstrap (CREATE TABLE … VECTOR, DBMS_VECTOR.CREATE_INDEX).
Supports COSINE, L2, and IP distance metrics.
CMake integration
New option VDB_WITH_ORACLE (ON by default).
Fetches and builds ODPI-C and links against Oracle Instant Client (libclntsh).
target_compile_definitions(DPI_CPP_WRAPPER_FOUND) lets the code know when the real ODPI-C headers are present; otherwise a tiny stub is compiled so the whole project still builds without Oracle.
Python bindings
vectorDB.list_backends() now shows ["oracle", "redis"].
Usage from Python is identical to Redis – see example below.
🔧 Building the Oracle backend

Install Instant Client (one–liner)
./scripts/fetch_instant_client.sh # downloads & unpacks 23.4 basiclite+sdk under /opt/oracle
sudo ldconfig # registers libclntsh
Manual install? Follow Oracle’s Instant Client docs. Make sure libclntsh.so is reachable either via LD_LIBRARY_PATH or /etc/ld.so.conf.d/oracle-instantclient.conf.
Configure & build
mkdir -B build && cd build
cmake .. -DVDB_WITH_ORACLE=ON # OFF if you want to skip Oracle
cmake --build . -j$(nproc) --target RagPUREAI
Verify
export PYTHONPATH="$PWD:$PYTHONPATH"
python - <<'PY'
import RagPUREAI
print(RagPUREAI.vectorDB.list_backends()) # ➜ ['oracle', 'redis']
PY
🐍 Python quick-start

import json, numpy as np
from RagPUREAI import RAGDocument
from RagPUREAI.vectorDB import make_backend

cfg = {
"user": "demo",
"password": "demo_pw",
"connect_string": "localhost/freepdb1", # EZ-connect, TNS or wallet
"dim": 1536,
"metric": "COSINE" # or "L2" / "IP"
}

db = make_backend("oracle", json.dumps(cfg))
assert db.is_open()

docs = [
RAGDocument({"id": "1"}, "hello oracle", np.random.rand(1536).tolist()),
RAGDocument({"id": "2"}, "another row", np.random.rand(1536).tolist()),
]
db.insert(docs)

qvec = np.random.rand(1536).tolist()
for rank, r in enumerate(db.query(qvec, k=2), 1):
print(rank, r.score, r.doc.page_content, r.doc.metadata)
db.close()
📂 Files touched

Path Purpose
components/VectorDatabase/src/backends/oracle_backend.cpp New backend
components/VectorDatabase/include/odpi.hpp Thin wrapper / stub forwarder
CMakeLists.txt VDB_WITH_ORACLE, ODPI-C fetch, Instant Client detection, rpath
components/VectorDatabase/python/binding_vectordb.cpp force_link_oracle_backend()
scripts/fetch_instant_client.sh Convenience installer
📝 Notes & caveats

Requires Oracle 23c/23ai or Autonomous DB with the AI Vector feature.
The build script looks for Instant Client 23.4 under /opt/oracle/instantclient_23_4; adjust OCI_LIB and OCI_INCLUDE_DIR in CMakeLists.txt if you keep it elsewhere.
If you disable Oracle (-DVDB_WITH_ORACLE=OFF) the stub kicks in so CI pipelines without Instant Client still build PureCPP.
Happy vector-searching! 🎉