# pg-cuvs/pg_cuvs architecture

> Architecture diagram of the GitHub repository pg-cuvs/pg_cuvs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pg-cuvs/pg_cuvs
- Repository: https://github.com/pg-cuvs/pg_cuvs

## Overview

#### 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`.

Main entry points: [`src/pg_cuvs.c`](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs.c) (Access methods & planner), [`src/pg_cuvs_server.c`](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs_server.c) (GPU service daemon), [`src/cuvs_wrapper.cu`](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper.cu) (cuVS wrapper), [`src/cuvs_ipc.c`](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_ipc.c) (Shared-memory IPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_postgres["PostgreSQL extension"]
  node_ddl["Extension DDL<br/>SQL install<br/>[pg_cuvs--0.5.0.sql]"]
  node_backend["Access methods &amp; planner<br/>PostgreSQL C extension<br/>[pg_cuvs.c]"]
  node_pgvector["pgvector<br/>compatibility dependency"]
  node_ipc["Shared-memory IPC<br/>backend-daemon protocol<br/>[cuvs_ipc.c]"]
  node_ipc_api["IPC interface<br/>C header<br/>[cuvs_ipc.h]"]
end

subgraph group_gpu["GPU service"]
  node_daemon{{"GPU service daemon<br/>CUDA-owning process<br/>[pg_cuvs_server.c]"}}
  node_wrapper["cuVS wrapper<br/>CUDA/C++ bridge<br/>[cuvs_wrapper.cu]"]
  node_wrapper_api["Wrapper interface<br/>C header<br/>[cuvs_wrapper.h]"]
  node_gpu_indexes[("VRAM index state")]
  node_cpu_shim["CPU kNN shim<br/>non-GPU implementation"]
end

subgraph group_artifacts["Index lifecycle"]
  node_corpus["Build corpus<br/>vector extraction"]
  node_corpus_api["Build corpus interface<br/>C header"]
  node_hnsw_export["HNSW export<br/>pgvector layout converter<br/>[hnsw_export.c]"]
  node_compaction["Artifact lifecycle<br/>updates and compaction"]
  node_objstore[("Object-store snapshots<br/>GCS integration<br/>[cuvs_objstore.c]")]
end

subgraph group_operations["Deployment and validation"]
  node_gcp["GCP GPU VM<br/>Terraform provisioning<br/>[main.tf]"]
  node_gpu_install["GPU environment install<br/>host setup script<br/>[install_gpu_env.sh]"]
  node_gpu_ci["GPU validation<br/>GitHub Actions workflow<br/>[gpu.yml]"]
  node_bench["Benchmark protocol<br/>benchmark orchestration<br/>[runner.py]"]
  node_bench_run["Benchmark launcher<br/>shell entry point<br/>[run.sh]"]
end

node_ddl -->|"installs AMs, types, operators"| node_backend
node_backend -->|"compatible SQL and CPU fallback"| node_pgvector
node_backend -->|"submits build/search"| node_ipc
node_ipc_api -->|"defines protocol"| node_ipc
node_ipc -->|"requests and responses"| node_daemon
node_daemon -->|"dispatches GPU work"| node_wrapper
node_wrapper_api -->|"stable C interface"| node_wrapper
node_wrapper -->|"builds and searches"| node_gpu_indexes
node_cpu_shim -.->|"implements interface for CI"| node_wrapper_api
node_backend -->|"initiates index build"| node_corpus
node_corpus_api -->|"defines corpus contract"| node_corpus
node_corpus -->|"supplies build data"| node_daemon
node_gpu_indexes -->|"exports graph and data"| node_hnsw_export
node_hnsw_export -->|"writes compatible HNSW layout"| node_pgvector
node_compaction -->|"refreshes stale artifacts"| node_gpu_indexes
node_objstore -.->|"restores snapshots"| node_gpu_indexes
node_gcp -->|"provisions host for"| node_gpu_install
node_gpu_install -.->|"enables CUDA runtime"| node_daemon
node_gpu_ci -.->|"validates GPU execution"| node_wrapper
node_bench_run -->|"launches"| node_bench
node_bench -.->|"measures extension paths"| node_backend

click node_ddl "https://github.com/pg-cuvs/pg_cuvs/blob/main/sql/pg_cuvs--0.5.0.sql"
click node_backend "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs.c"
click node_ipc "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_ipc.c"
click node_ipc_api "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_ipc.h"
click node_daemon "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs_server.c"
click node_wrapper "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper.cu"
click node_wrapper_api "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper.h"
click node_cpu_shim "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper_shim_cpu.c"
click node_corpus "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_build_corpus.c"
click node_corpus_api "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_build_corpus.h"
click node_hnsw_export "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/hnsw_export.c"
click node_compaction "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs_compaction.c"
click node_objstore "https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_objstore.c"
click node_gcp "https://github.com/pg-cuvs/pg_cuvs/blob/main/infra/gcp/main.tf"
click node_gpu_install "https://github.com/pg-cuvs/pg_cuvs/blob/main/infra/gcp/scripts/install_gpu_env.sh"
click node_gpu_ci "https://github.com/pg-cuvs/pg_cuvs/blob/main/.github/workflows/gpu.yml"
click node_bench "https://github.com/pg-cuvs/pg_cuvs/blob/main/bench/protocol/runner.py"
click node_bench_run "https://github.com/pg-cuvs/pg_cuvs/blob/main/bench/protocol/run.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ddl,node_backend,node_pgvector,node_ipc,node_ipc_api toneBlue
class node_daemon,node_wrapper,node_wrapper_api,node_gpu_indexes,node_cpu_shim toneAmber
class node_corpus,node_corpus_api,node_hnsw_export,node_compaction,node_objstore toneMint
class node_gcp,node_gpu_install,node_gpu_ci,node_bench,node_bench_run toneRose
```

## Components

### PostgreSQL extension

SQL, access methods, and PostgreSQL-owned query semantics.

- [Extension DDL](https://github.com/pg-cuvs/pg_cuvs/blob/main/sql/pg_cuvs--0.5.0.sql): SQL install · `sql/pg_cuvs--0.5.0.sql`
- [Access methods & planner](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs.c): PostgreSQL C extension · Preserves planner, MVCC, heap access, and final filtering. · `src/pg_cuvs.c`
- **pgvector**: compatibility dependency · Supplies compatible vector semantics and CPU HNSW serving.
- [Shared-memory IPC](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_ipc.c): backend-daemon protocol · Carries build and search requests without backend CUDA contexts. · `src/cuvs_ipc.c`
- [IPC interface](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_ipc.h): C header · `src/cuvs_ipc.h`

### GPU service

Daemon-owned CUDA execution and GPU index state.

- [GPU service daemon](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs_server.c): CUDA-owning process · Dispatches tasks and owns service lifecycle and GPU resources. · `src/pg_cuvs_server.c`
- [cuVS wrapper](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper.cu): CUDA/C++ bridge · Isolates CUDA and cuVS from PostgreSQL runtime integration. · `src/cuvs_wrapper.cu`
- [Wrapper interface](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper.h): C header · `src/cuvs_wrapper.h`
- **VRAM index state**: CAGRA / IVF / flat · Daemon-resident GPU search artifacts.
- [CPU kNN shim](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_wrapper_shim_cpu.c): non-GPU implementation · Provides exact CPU reference execution for CI. · `src/cuvs_wrapper_shim_cpu.c`

### Index lifecycle

Build, persistence, export, and artifact maintenance.

- [Build corpus](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_build_corpus.c): vector extraction · Reads PostgreSQL vector data for GPU index construction. · `src/cuvs_build_corpus.c`
- [Build corpus interface](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_build_corpus.h): C header · `src/cuvs_build_corpus.h`
- [HNSW export](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/hnsw_export.c): pgvector layout converter · Converts GPU-built graph/data into pgvector on-disk HNSW pages. · `src/hnsw_export.c`
- [Artifact lifecycle](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/pg_cuvs_compaction.c): updates and compaction · Manages tombstones, stale GPU artifacts, and compaction. · `src/pg_cuvs_compaction.c`
- [Object-store snapshots](https://github.com/pg-cuvs/pg_cuvs/blob/main/src/cuvs_objstore.c): GCS integration · Supports credentialed bucket-backed restore. · `src/cuvs_objstore.c`

### Deployment and validation

GPU provisioning, validation, and benchmarking.

- [GCP GPU VM](https://github.com/pg-cuvs/pg_cuvs/blob/main/infra/gcp/main.tf): Terraform provisioning · `infra/gcp/main.tf`
- [GPU environment install](https://github.com/pg-cuvs/pg_cuvs/blob/main/infra/gcp/scripts/install_gpu_env.sh): host setup script · `infra/gcp/scripts/install_gpu_env.sh`
- [GPU validation](https://github.com/pg-cuvs/pg_cuvs/blob/main/.github/workflows/gpu.yml): GitHub Actions workflow · Runs real-GPU validation separately from CPU-reference checks. · `.github/workflows/gpu.yml`
- [Benchmark protocol](https://github.com/pg-cuvs/pg_cuvs/blob/main/bench/protocol/runner.py): benchmark orchestration · Coordinates comparable engine runs. · `bench/protocol/runner.py`
- [Benchmark launcher](https://github.com/pg-cuvs/pg_cuvs/blob/main/bench/protocol/run.sh): shell entry point · `bench/protocol/run.sh`

## Connections

- Extension DDL → Access methods & planner: installs AMs, types, operators
- Access methods & planner → pgvector: compatible SQL and CPU fallback
- Access methods & planner → Shared-memory IPC: submits build/search
- IPC interface → Shared-memory IPC: defines protocol
- Shared-memory IPC → GPU service daemon: requests and responses
- GPU service daemon → cuVS wrapper: dispatches GPU work
- Wrapper interface → cuVS wrapper: stable C interface
- cuVS wrapper → VRAM index state: builds and searches
- CPU kNN shim → Wrapper interface: implements interface for CI
- Access methods & planner → Build corpus: initiates index build
- Build corpus interface → Build corpus: defines corpus contract
- Build corpus → GPU service daemon: supplies build data
- VRAM index state → HNSW export: exports graph and data
- HNSW export → pgvector: writes compatible HNSW layout
- Artifact lifecycle → VRAM index state: refreshes stale artifacts
- Object-store snapshots → VRAM index state: restores snapshots
- GCP GPU VM → GPU environment install: provisions host for
- GPU environment install → GPU service daemon: enables CUDA runtime
- GPU validation → cuVS wrapper: validates GPU execution
- Benchmark launcher → Benchmark protocol: launches
- Benchmark protocol → Access methods & planner: measures extension paths