pgvector-rust

pgvector-rust adds first-class Rust types for the pgvector Postgres extension, letting applications store and query embeddings without hand-rolling binary encoding logic. It ships Vector, HalfVector, SparseVector, and Bit types with conversions to and from Rust’s native slice and Vec types, so vectors move between application code and Postgres columns using ordinary Rust idioms.

The crate wires into three of Rust’s most common Postgres access layers — the low-level rust-postgres/tokio-postgres client, SQLx, and Diesel — via optional feature flags, so teams keep whatever query layer they already use while gaining typed vector columns, nearest-neighbor distance operators, and optional serde serialization.

What You Get

• Vector, HalfVector, SparseVector, and Bit types with conversions to and from native Rust Vec/slice types.
• Feature-gated integrations for rust-postgres, SQLx, and Diesel so you only compile what you use.
• Diesel VectorExpressionMethods for distance operators (l2_distance, cosine_distance, max_inner_product, l1_distance, hamming_distance, jaccard_distance) usable directly in query builders.
• Optional serde support for JSON serialization/deserialization of vector values.
• Runnable examples covering OpenAI/Cohere embeddings, Candle sentence embeddings, hybrid search, recommendations, horizontal scaling with Citus, and bulk loading via COPY.

Common Use Cases

• Storing LLM embeddings - applications persist OpenAI, Cohere, or local model embeddings as typed Vector columns instead of raw byte arrays.
• Nearest-neighbor search - services query for similar rows using Postgres’s distance operators through typed driver bindings.
• Diesel query composition - teams already on Diesel add vector distance ordering and filtering to existing query builders via VectorExpressionMethods.
• Memory-efficient embedding storage - the halfvec feature stores half-precision embeddings to cut storage size for large embedding tables.
• Hybrid and sparse search - SparseVector supports keyword-style sparse retrieval alongside dense embeddings for reciprocal rank fusion.

Under The Hood

Architecture The crate is organized around four value types (Vector, HalfVector, SparseVector, Bit), each defined once in its own src file with pure-Rust conversions and a shared binary decoder for pgvector’s Postgres wire format. Three separate integration modules — postgres_ext, sqlx_ext, diesel_ext — then implement the trait glue each specific driver crate expects (ToSql/FromSql for postgres-types, Encode/Decode for SQLx, FromSqlRow/AsExpression plus six infix SQL operators for Diesel), all gated behind Cargo feature flags (postgres, sqlx, diesel, halfvec, serde) so consumers compile in only what they use. lib.rs is a thin re-export and feature-gating layer with no logic of its own. The Diesel operators (L2Distance, MaxInnerProduct, CosineDistance, L1Distance, HammingDistance, JaccardDistance) map one-to-one onto pgvector’s native Postgres operators via diesel::infix_operator!. The component every driver integration leans on is each type’s from_sql binary-layout parser — a change there would ripple through all three driver modules at once.

Tech Stack Rust 2021 edition, minimum supported Rust version 1.60. Core optional dependencies: postgres-types and bytes for the rust-postgres integration, sqlx (>=0.8, <0.10) with the postgres feature, diesel 2 with the postgres feature, half for the halfvec feature, and serde with derive for the serde feature — each gated so unused drivers add zero compile weight. Dev-dependencies (postgres, tokio-postgres, tokio, serde_json) support integration tests only. CI builds pgvector from source against a live Postgres instance and runs cargo test across every feature combination (postgres, sqlx, diesel, serde, and each paired with halfvec).

Code Quality 23 #[test] functions span unit tests for pure conversions (dense-to-sparse, map construction, serde round-trips) and integration tests that stand up a real Postgres connection via rust-postgres and tokio-postgres, insert vectors, and assert on both binary and text encodings. Error handling in the binary decoders is explicit — from_sql returns a Result and validates buffer length and reserved bytes rather than panicking — though a few dimension-cast paths (SparseVector::from_dense, from_map, to_vec) use unwrap() on try_into() rather than propagating an error. There is no clippy or rustfmt configuration checked into the repo, and CI runs cargo test only, without a lint gate. Naming and structure follow idiomatic Rust conventions throughout.

API Design The crate keeps the public surface small and predictable: each vector type offers From/Into conversions to Rust’s native Vec and slice types, so callers rarely touch the crate’s internals directly. Enabling a driver is a single Cargo feature flag rather than a separate crate or wrapper API, and Diesel users get distance operators as ordinary query-builder methods (VectorExpressionMethods) rather than raw SQL strings. Getting started requires no boilerplate beyond adding the feature flag and running CREATE EXTENSION — the eight bundled examples (OpenAI, Cohere, Candle, hybrid search, Citus, bulk loading) double as end-to-end onboarding docs.