CLAUDE.md
Guidance for Claude Code (and other agents) working in this repo.
What this is
Pinecone for Postgres (pg_pinecone): a Postgres extension that backs one pgvector column
with three interchangeable engines — pgvector, native (Pinecone’s engine in-process),
and remote (Pinecone serverless). Rust + pgrx,
workspace of two crates: pg_pinecone (the extension) and pg_pinecone-client (pure Rust, no Postgres).
Build & test
cargo test -p pg_pinecone-client # client crate, no Postgres needed
./scripts/install-pgvector.sh # one-time: pgvector into the pgrx-managed Postgres
cd pg_pinecone && cargo pgrx test pg17 # extension tests incl. e2e vs a mock (pg18 likewise)
cargo fmt --all && cargo clippy --workspace --all-targets -- -D warnings
CI required checks: pgrx-tests-pg17/pg18, upgrade-test-pg17/pg18, lint, client-tests.
Main requires green CI; don’t merge red.
Diagnosing an install: SELECT * FROM pinecone.doctor() (remote => false makes no request) lists
version, preload, pgvector, credentials, URL, Pinecone reachability, worker, outbox and failed partitions
as ok/warn/fail with a hint. A new setup or failure check belongs in pg_pinecone/src/doctor.rs, and an
error about setup, credentials or reachability should point at it.
Invariants that bite
- Upgrades are in place from 0.10.0 on (the rename from
pinegreswas the last clean break). Anything that changes whatCREATE EXTENSIONbuilds needs a line inpg_pinecone/sql/pg_pinecone--<prev>--<new>.sql, orupgrade-testfails. Full rules in docs/contributing.md. - Don’t break a shipped
#[pg_extern]. Its C symbol and call shape must stay until an upgrade script drops it. New SQL signature = new Rust function, not a changed one. - The restart precedes the update, so the new library serves the old catalog for a
window. Code that runs before
ALTER EXTENSION UPDATEmust work without new columns/kinds. - On-disk layout changes bump the index format version (
FORMAT_VERSIONinlocal/metapage.rs) and add a reader branch or a refusal. - Clean-room provenance. Algorithm modules are implemented from published papers only — no code from any proprietary or third-party implementation. Cite the paper in the module header; test against an independent oracle, not another implementation.
Conventions
- Keep comments and PR text short; state the why in as few words as possible.
- Match the surrounding code’s idiom and comment density.
- See docs/contributing.md for the upgrade-script authoring loop and the full schema-change checklist, and the runbook for operational detail.