pg-cuvs/pg_cuvs

Purpose and Entry Points

pg_cuvs is a PostgreSQL 16 extension that preserves pgvector SQL, MVCC, and planner control while offloading vector index build/search work to NVIDIA cuVS GPUs. PostgreSQL loads the extension through pg_cuvs.control and versioned SQL DDL in sql/pg_cuvs--0.5.0.sql; the backend extension entry and access-method registration are in src/pg_cuvs.c. A separate GPU service daemon is implemented in src/pg_cuvs_server.c.

PostgreSQL Access Methods and Planner Boundary

The extension exposes GPU-resident CAGRA, exact flat, and IVF-PQ paths, plus pg_cuvs_hnsw for GPU-built but CPU-served pgvector-compatible HNSW indexes. PostgreSQL remains responsible for query planning, heap access, joins, visibility, and final filtering; GPU results are candidate TIDs/distances. Core AM and planner integration live in src/pg_cuvs.c, with SQL-visible types/functions/operators installed from sql/pg_cuvs--0.5.0.sql.

Backend-to-Daemon IPC

PostgreSQL backend processes do not create CUDA contexts. They submit build/search requests over shared-memory IPC to one tightly coupled daemon, avoiding per-session CUDA VRAM and initialization costs. IPC structures, request flow, and failure handling are centered in src/cuvs_ipc.c and src/cuvs_ipc.h; daemon task dispatch, CUDA-context ownership, and service lifecycle are in src/pg_cuvs_server.c. If this boundary is unavailable, the extension fails closed or routes to CPU/standard pgvector paths rather than interrupting database service.

GPU Execution and Index Artifacts

The daemon owns cuVS CAGRA/IVF/brute-force execution and VRAM-resident index state. The CUDA/C++ integration boundary is src/cuvs_wrapper.cu with its stable C-facing interface in src/cuvs_wrapper.h; src/cuvs_wrapper_shim_cpu.c substitutes exact CPU kNN for non-GPU CI. This isolates PostgreSQL C headers/runtime from CUDA and makes daemon/backend protocol correctness testable without CUDA.

Build, Persistence, and HNSW Export

Index construction reads PostgreSQL vector data into a GPU-buildable corpus, represented by src/cuvs_build_corpus.c and src/cuvs_build_corpus.h. CAGRA may remain a GPU-search artifact, or its graph/data is converted into pgvector’s on-disk HNSW layout through src/hnsw_export.c. The latter enables normal PostgreSQL catalog ownership, DROP INDEX, REINDEX, backup semantics, and CPU pgvector serving, but creates an intentional compatibility dependency on pgvector’s HNSW page format.

Stateful Operations and External Storage

The extension includes lifecycle management for updates, tombstones, stale GPU artifacts, and compaction in src/pg_cuvs_compaction.c. Snapshot/object-store integration is separated in src/cuvs_objstore.c and src/cuvs_objstore.h; operationally this supports GCS-backed restore when PostgreSQL credentials and bucket configuration are supplied. Multi-GPU sharding and MIG operate through CUDA device visibility and daemon-managed GPU resources rather than a distributed database control plane.

Runtime, Deployment, and Validation

Material dependencies are PostgreSQL 16, pgvector, CUDA 12+, RAPIDS cuVS, NVIDIA drivers, and a Linux GPU host. GCP GPU VM provisioning is defined in infra/gcp/main.tf, while GPU environment installation is scripted in infra/gcp/scripts/install_gpu_env.sh. CPU-reference correctness uses the wrapper shim; real-GPU validation is separately triggered in .github/workflows/gpu.yml. Benchmark orchestration and comparable engine runs are organized under bench/protocol/run.sh and bench/protocol/runner.py.