enuno/langchain-postgres

LangChain Postgres Skill

Expert assistance for langchain-postgres: pgvector-backed vector store and PostgreSQL chat history for LangChain. Use v2 API (PGVectorStore + PGEngine) for new projects; v1 (PGVector) is legacy.

Install:

pip install -U langchain-postgres psycopg[binary] psycopg-pool
# Start PostgreSQL with pgvector:
docker run -p 5432:5432 -e POSTGRES_PASSWORD=password pgvector/pgvector:pg16

Reference: references/api.md (500 KB — full API reference).

When to Use This Skill

Activate when:

• Creating a pgvector store (v2) — using PGEngine + PGVectorStore.create() or create_sync()
• Using legacy PGVector (v1) — constructing PGVector with connection_string directly
• Initializing the vector table — calling engine.init_vectorstore_table() before first use
• Adding HNSW or IVFFlat indexes — using apply_vector_index() with HNSWIndex or IVFFlatIndex
• Hybrid search — configuring HybridSearchConfig with weighted_sum_ranking or reciprocal_rank_fusion
• Adding custom metadata columns — using Column / ColumnDict in table initialization
• Persisting chat history in Postgres — using PostgresChatMessageHistory with sync or async psycopg connections
• Async vector store operations — using AsyncPGVectorStore or the async methods on PGVectorStore
• Managing indexes — calling drop_vector_index(), reindex(), is_valid_index()

Quick Reference

v2 API — PGEngine + PGVectorStore (recommended for new projects)

from langchain_postgres.v2.engine import PGEngine
from langchain_postgres.v2.vectorstores import PGVectorStore
from langchain_openai import OpenAIEmbeddings

# Step 1: create engine (manages async connection pool)
engine = PGEngine.from_connection_string(
    url="postgresql+asyncpg://user:password@localhost:5432/mydb"
)

# Step 2: initialize the table (run once)
engine.init_vectorstore_table(
    table_name="my_vectors",
    vector_size=1536,           # must match embedding dimension
    # overwrite_existing=False  # set True to recreate
)

# Step 3: create the vector store (use factory, NOT constructor)
vector_store = PGVectorStore.create_sync(
    engine=engine,
    embedding_service=OpenAIEmbeddings(),
    table_name="my_vectors",
)

# Add documents
from langchain_core.documents import Document
docs = [Document(page_content="LangChain is a framework.", metadata={"source": "docs"})]
vector_store.add_documents(docs)

# Search
results = vector_store.similarity_search("What is LangChain?", k=3)

# Cleanup
engine.close()

v2 API — async usage

import asyncio
from langchain_postgres.v2.engine import PGEngine
from langchain_postgres.v2.vectorstores import PGVectorStore
from langchain_openai import OpenAIEmbeddings

async def main():
    engine = PGEngine.from_connection_string(
        url="postgresql+asyncpg://user:password@localhost:5432/mydb"
    )
    await engine.ainit_vectorstore_table("my_vectors", vector_size=1536)

    store = await PGVectorStore.create(
        engine=engine,
        embedding_service=OpenAIEmbeddings(),
        table_name="my_vectors",
    )

    await store.aadd_documents(docs)
    results = await store.asimilarity_search("LangChain", k=3)
    await engine.close()

asyncio.run(main())

v2 API — HNSW index for fast approximate search

from langchain_postgres.v2.indexes import HNSWIndex, HNSWQueryOptions, DistanceStrategy

# Apply HNSW index after loading data
vector_store.apply_vector_index(
    HNSWIndex(
        name="hnsw_idx",
        distance_strategy=DistanceStrategy.COSINE,
        m=16,           # max connections per node (default 16)
        ef_construction=64,  # build-time search width (default 64)
    )
)

# Use optimized query options at search time
results = vector_store.similarity_search(
    "my query",
    k=5,
    query_options=HNSWQueryOptions(ef_search=40),
)

# IVFFlat for larger datasets
from langchain_postgres.v2.indexes import IVFFlatIndex, IVFFlatQueryOptions
vector_store.apply_vector_index(
    IVFFlatIndex(name="ivfflat_idx", lists=100)
)
results = vector_store.similarity_search(
    "my query", k=5, query_options=IVFFlatQueryOptions(probes=10)
)

v2 API — hybrid search (vector + full-text)

from langchain_postgres.v2.hybrid_search_config import (
    HybridSearchConfig,
    reciprocal_rank_fusion,
    weighted_sum_ranking,
)

# Configure hybrid search on the store
vector_store.apply_hybrid_search_index(
    HybridSearchConfig(
        ranking_function=reciprocal_rank_fusion,   # or weighted_sum_ranking
        # For weighted_sum_ranking:
        # ranking_function=weighted_sum_ranking,
        # alpha=0.7,  # weight for vector score (0=full-text only, 1=vector only)
    )
)

results = vector_store.similarity_search("my query", k=5, search_type="hybrid")

v2 API — custom metadata columns

from langchain_postgres.v2.engine import PGEngine, Column

engine.init_vectorstore_table(
    table_name="my_vectors",
    vector_size=1536,
    metadata_columns=[
        Column(name="source", data_type="TEXT"),
        Column(name="created_at", data_type="TIMESTAMP"),
        Column(name="score", data_type="FLOAT"),
    ],
)

v1 API — legacy PGVector (simple setup)

from langchain_postgres import PGVector
from langchain_openai import OpenAIEmbeddings

# Direct constructor (v1 only)
vector_store = PGVector(
    embeddings=OpenAIEmbeddings(),
    collection_name="my_collection",
    connection="postgresql+psycopg://user:password@localhost:5432/mydb",
    # distance_strategy=DistanceStrategy.COSINE,
    # use_jsonb=True,
)

vector_store.add_documents(docs)
results = vector_store.similarity_search("LangChain", k=3)

PostgresChatMessageHistory (sync and async)

import psycopg
from langchain_postgres import PostgresChatMessageHistory
from langchain_core.messages import HumanMessage, AIMessage

# Create table (run once)
conn_info = "postgresql://user:password@localhost:5432/mydb"
sync_conn = psycopg.connect(conn_info)
PostgresChatMessageHistory.create_tables(sync_conn, "chat_history")

# Use in a session
history = PostgresChatMessageHistory(
    table_name="chat_history",
    session_id="user-session-xyz",
    sync_connection=sync_conn,
)
history.add_messages([
    HumanMessage(content="Hello!"),
    AIMessage(content="Hi! How can I help?"),
])
print(history.messages)
history.clear()

# Async version
async def async_history():
    async_conn = await psycopg.AsyncConnection.connect(conn_info)
    await PostgresChatMessageHistory.acreate_tables(async_conn, "chat_history")
    history = PostgresChatMessageHistory(
        table_name="chat_history",
        session_id="user-abc",
        async_connection=async_conn,
    )
    await history.aadd_messages([HumanMessage(content="Hi")])
    msgs = await history.aget_messages()

v1 vs v2 Decision Guide

| Aspect | v1 PGVector | v2 PGVectorStore | |--------|--------------|-------------------| | Construction | Direct constructor | Factory: create() / create_sync() | | Connection | connection_string param | PGEngine.from_connection_string() | | Async | Limited | First-class async throughout | | Indexes | Manual SQL | apply_vector_index(HNSWIndex(...)) | | Hybrid search | No | Yes (HybridSearchConfig) | | Custom columns | Limited | Column / ColumnDict | | Table management | Auto | init_vectorstore_table() required | | Use for | Legacy/simple | New projects |

API Reference

PGEngine (v2)

| Method | Description | |--------|-------------| | PGEngine.from_connection_string(url) | Create engine from connection string | | PGEngine.from_engine(engine) | Wrap existing SQLAlchemy AsyncEngine | | engine.init_vectorstore_table(table, vector_size, ...) | Create vector table | | engine.drop_table(table_name) | Drop a table | | engine.close() | Close connection pool |

PGVectorStore (v2) key methods

| Method | Description | |--------|-------------| | PGVectorStore.create_sync(engine, embedding, table_name) | Sync factory | | PGVectorStore.create(engine, embedding, table_name) | Async factory (awaitable) | | add_documents(docs) / aadd_documents(docs) | Add documents | | similarity_search(query, k) / asimilarity_search(...) | Vector search | | similarity_search_with_score(query, k) | Search with distance scores | | max_marginal_relevance_search(query, k, fetch_k) | MMR diversity search | | apply_vector_index(index) | Apply HNSW or IVFFlat index | | apply_hybrid_search_index(config) | Enable hybrid search | | drop_vector_index(name) | Remove an index | | reindex(name) | Rebuild an index | | is_valid_index(name) | Check index health |

Reference Files

| File | Size | Contents | |------|------|----------| | references/api.md | 500 KB | Full API reference (all classes, methods) | | references/llms.md | 28 KB | Doc index | | references/llms-full.md | 500 KB | Complete page content |

Requires: PostgreSQL with pgvector extension (pgvector/pgvector:pg16 Docker image).
Source: https://reference.langchain.com/python/langchain-postgres
GitHub: https://github.com/langchain-ai/langchain-postgres