TramAI - governed AI workflows for Java and Kotlin

tramai-vectorstore-pgvector

Version: 0.6.0
Status: Preview (published)
Role: PostgreSQL pgvector implementation of the vector store SPI.

Purpose

This module provides a concrete implementation of VectorStore backed by PostgreSQL with the pgvector extension. Vectors live in ordinary tables next to your relational data, so document metadata and vectors share one transactional boundary. Failures surface as PgVectorException.

Dependencies

// build.gradle.kts
dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-vectorstore-pgvector")
    runtimeOnly("org.postgresql:postgresql") // the store loads org.postgresql.Driver
}

The store manages its own HikariCP pool internally — you pass connection coordinates, not a DataSource.

Quick Start

import dev.tramai.embedding.OpenAiEmbeddingModel
import dev.tramai.vectorstore.VectorEntry
import dev.tramai.vectorstore.pgvector.PgVectorStore

val embeddings = OpenAiEmbeddingModel(apiKey = System.getenv("OPENAI_API_KEY"))
val store = PgVectorStore(
    jdbcUrl = "jdbc:postgresql://localhost:5432/rag",
    user = "rag",
    password = System.getenv("PG_PASSWORD"),
    dimensions = 1536, // must match the embedding model
)

val text = "Postgres can store vectors next to relational data."
store.upsert(
    collection = "my_docs",
    vectors = listOf(
        VectorEntry(
            id = "doc-1",
            vector = embeddings.embed(text),
            content = text,
            metadata = mapOf("source" to "handbook"),
        ),
    ),
)

val results = store.search(
    collection = "my_docs",
    query = embeddings.embed("Where do vectors live?"),
    topK = 3,
)

The table for a collection is created on first write, and the vector extension is enabled as part of the pool's connection initialization. Collection names must start with a letter and contain only alphanumerics/underscores (the table is named vec_<collection>, or <tablePrefix>_<collection> when a prefix is set).

When to use this module

  • You are already using PostgreSQL as your primary database.
  • You prefer to keep relational data and vector data in the same transactional boundary.
  • You do not want to manage a separate standalone vector database.

When NOT to use this module

  • Your Postgres instance does not support the pgvector extension.
  • You are operating at an extremely large vector scale where specialized cluster databases are required.
Previous
Next