Documentation
¶
Overview ¶
Package pgvector implements the second external VectorIndex adapter (ADR-05, REQ-VEC-001/002). It uses the pgx pure-Go driver (zero-CGO) to talk to a PostgreSQL database with the pgvector extension.
SERVER-TRACK BOUNDARY: this package is SERVER-track (arch_test.go bans it from local composition). The local composition path (internal/app) wires the sqlite_blob zero-CGO default and MUST NOT import this package. Provider selection (pgvector.New) happens ONLY in the server/external composition path. This preserves REQ-FOUND-001: CGO_ENABLED=0 local build with zero external vector dependencies.
ISOLATED REPLICA: SQLite remains authoritative for observation data. The pgvector table is a vector REPLICA keyed by observation ID (BIGINT PK from SQLite). This is NOT a full Postgres source-of-truth (W11) — it is a read-optional dense candidate source for vector similarity search. No observation metadata (content, timestamps, lifecycle) is replicated; only the vector embedding and the filter columns needed for PreFilter/PostFilter search.
Schema/table isolation: the adapter creates its own schema (default cortex_vector) and table (default embeddings). These identifiers are validated against a safe regex before interpolation into SQL (schema/table names cannot be parameterized in PostgreSQL DDL). All data values use parameterized queries ($N) — no string interpolation of user data.
Dimension/model mismatch are rejected FAIL-CLOSED before any DB call (REQ-VEC-001 dim-mismatch corruption pin; model-namespace mismatch).
No plaintext secrets: the DSN password is extracted at construction time and scrubbed from every error message via redactWith (REQ-CP-002). The DSN is NEVER logged or surfaced in error strings.
Statement/query timeouts: every operation runs under a context with a configurable deadline, AND each transaction sets statement_timeout via set_config (server-side kill on slow queries).
Index ¶
- type Adapter
- func (a *Adapter) Capabilities(_ context.Context) (domain.Capabilities, error)
- func (a *Adapter) Close() error
- func (a *Adapter) Delete(ctx context.Context, ids []int64) error
- func (a *Adapter) Health(ctx context.Context) domain.Health
- func (a *Adapter) ID() string
- func (a *Adapter) Search(ctx context.Context, q domain.VectorQuery) ([]domain.VectorCandidate, error)
- func (a *Adapter) Upsert(ctx context.Context, points []domain.VectorPoint) error
- type AdapterConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter implements domain.VectorIndex over a PostgreSQL database with the pgvector extension via the pgx pure-Go driver.
func New ¶
func New(ctx context.Context, cfg AdapterConfig) (*Adapter, error)
New constructs a pgvector Adapter with a real pgxpool connection pool. The caller MUST be in the server/external composition path (this package is server-track). The returned Adapter owns its pool; Close closes it.
Bootstrap: New connects with a raw pgx.Conn first to create the extension, schema, table, and index, then creates the pool. This ensures the vector type exists before any pooled connection uses it.
func NewWithDB ¶
func NewWithDB(db pgvectorDB, cfg AdapterConfig) (*Adapter, error)
NewWithDB constructs an Adapter over a pre-built (or fake) DB. Used by tests and by compositions that manage the pool lifecycle externally. The caller controls whether Close closes the pool (see ownDB; default false).
func (*Adapter) Capabilities ¶
Capabilities declares the adapter's supported features for capability-driven strategy selection (ADR-05).
func (*Adapter) Close ¶
Close releases resources. If the adapter owns its pool (factory-built via New), the underlying pool is closed.
func (*Adapter) Delete ¶
Delete removes vectors by observation ID using a parameterized ANY($1) clause. Missing IDs are tolerated (idempotent delete).
func (*Adapter) Health ¶
Health reports the adapter's current health by pinging the PostgreSQL pool. The DSN/password is never included in the health message.
func (*Adapter) Search ¶
func (a *Adapter) Search(ctx context.Context, q domain.VectorQuery) ([]domain.VectorCandidate, error)
Search translates a domain.VectorQuery into a parameterized SELECT against the pgvector table. Filters are mapped to WHERE conditions (PostFilter). The score threshold is applied client-side after receiving results.
type AdapterConfig ¶
type AdapterConfig struct {
DSN string // PostgreSQL runtime connection string
BootstrapDSN string // optional privileged DDL connection; empty falls back to DSN
Schema string // schema name (default cortex_vector)
Table string // table name (default embeddings)
Dimension int // expected vector dimension
ModelName string // model name for namespace enforcement (empty = skip)
IndexType string // hnsw or ivfflat (default hnsw)
HNSWM int // HNSW max connections per node (default 16, range 2-100)
HNSWEfConstruction int // HNSW dynamic candidate list for build (default 64, range 1-1000)
IVFFlatLists int // IVFFlat number of inverted lists (default 100, range 1-50000)
MaxBatchSize int // upsert batch ceiling (default 256)
Timeout time.Duration // per-operation timeout (default 30s)
MaxConns int32 // pool max connections (default 10)
StatementTimeoutMs int // PostgreSQL statement_timeout in ms (default 5000)
}
AdapterConfig holds the parameters to construct a pgvector Adapter. It mirrors config.PGVectorConfig but is declared here so the adapter package is self-contained (the server composition path maps config.PGVectorConfig → AdapterConfig). Index tuning uses typed validated integers — there is NO raw SQL string surface for index options (prevents injection via DDL).
Source Files