LangChain PostgreSQL Integration

Warnings

• breaking In versions 0.0.14 and higher, the `PGVector` class has been deprecated. Users should migrate to `PGVectorStore` for improved performance and manageability.
  Fix: Replace `PGVector` imports and instantiations with `PGVectorStore`. Refer to the official migration guide for detailed steps.
• gotcha When using `PostgresSaver` (from `langgraph.checkpoint.postgres`) with manually created PostgreSQL connections, it is crucial to include `autocommit=True` and `row_factory=dict_row` in the connection parameters. Failure to do so can lead to `TypeError` exceptions due to incorrect row access (tuple vs. dictionary) and unpersisted table creations after `.setup()` calls.
  Fix: Ensure your connection string or connection object creation includes `autocommit=True` and `row_factory=dict_row` (e.g., `from psycopg.rows import dict_row`). For production, consider `ConnectionPool` from `psycopg_pool` to manage connections.
• breaking The connection string format has changed for `langchain-postgres` to explicitly work with `psycopg3`. Update connection strings from `postgresql+psycopg2://...` to `postgresql+psycopg://...`.
  Fix: Modify your PostgreSQL connection strings to use `postgresql+psycopg://` as the scheme instead of `postgresql+psycopg2://`.
• gotcha For `PostgresSaver`, when the database is first used, the `.setup()` method must be called to create the required tables. Operations will fail if tables are not initialized.
  Fix: Always call `checkpointer.setup()` on your `PostgresSaver` instance when setting it up for the first time or when ensuring table existence.
• gotcha LangChain applications, especially those using checkpoints in production deployments, can suffer from 'too many clients already' errors if the PostgreSQL connection limit is exceeded. This is often due to a high number of runs, large checkpoint sizes, or unmanaged connection pools.
  Fix: Optimize connection pool settings (e.g., `ASYNCPG_POOL_MAX_SIZE`, `ASYNCPG_POOL_MIN_SIZE`), increase PostgreSQL `max_connections`, implement connection retry logic, and consider using a connection pooler like PgBouncer.

Install

• pip install -U langchain-postgres Latest Stable Release
• pip install -U 'langchain-postgres[psycopg]' # for psycopg3 driver With Psycopg3 Driver
• pip install -U 'langchain-postgres[asyncpg]' # for asyncpg driver With Asyncpg Driver

Imports

• PGEngine

  from langchain_postgres import PGEngine

• PGVectorStore

  from langchain_postgres import PGVectorStore

• PostgresChatMessageHistory

  from langchain_postgres.chat_message_histories import PostgresChatMessageHistory

• PostgresSaver

  from langgraph.checkpoint.postgres import PostgresSaver

  PostgresSaver for LangGraph checkpoints is located in `langgraph.checkpoint.postgres`, not directly in `langchain_postgres`.
• PGVector

  from langchain_postgres.vectorstores import PGVector

  As of v0.0.14+, `PGVector` is deprecated. Migrate to `PGVectorStore` for improved performance and manageability.

Quickstart

This quickstart demonstrates how to set up `PGEngine` for connecting to PostgreSQL, initialize a `PGVectorStore` for document embedding and similarity search, and use `PostgresChatMessageHistory` for persisting chat messages. It uses `DeterministicFakeEmbedding` for demonstration purposes; in a real application, you would replace this with an actual embedding model. Remember to set your `POSTGRES_CONNECTION_STRING` environment variable.

import os
from langchain_core.documents import Document
from langchain_core.embeddings import DeterministicFakeEmbedding
from langchain_postgres import PGEngine, PGVectorStore

# Replace with your PostgreSQL connection string
CONNECTION_STRING = os.environ.get('POSTGRES_CONNECTION_STRING', 'postgresql+psycopg://langchain:langchain@localhost:6024/langchain')

# Initialize PGEngine
engine = PGEngine.from_connection_string(url=CONNECTION_STRING)

# Define vector size and embedding service
VECTOR_SIZE = 768  # Adjust based on your embedding model
embedding = DeterministicFakeEmbedding(size=VECTOR_SIZE)
TABLE_NAME = "my_doc_collection"

# Initialize the vector store table (if it doesn't exist)
engine.init_vectorstore_table(
    table_name=TABLE_NAME,
    vector_size=VECTOR_SIZE,
)

# Create a synchronous PGVectorStore instance
store = PGVectorStore.create_sync(
    engine=engine,
    table_name=TABLE_NAME,
    embedding_service=embedding,
)

# Add documents
docs = [
    Document(page_content="Apples and oranges"),
    Document(page_content="Cars and airplanes"),
    Document(page_content="Dogs and cats"),
]
store.add_documents(docs)

# Perform a similarity search
query = "fruits"
results = store.similarity_search(query, k=1)
print(f"Similarity search for '{query}': {results[0].page_content}")

# Example for Chat Message History
from langchain_postgres.chat_message_histories import PostgresChatMessageHistory
import uuid

session_id = str(uuid.uuid4())
chat_history = PostgresChatMessageHistory(session_id=session_id, table_name="chat_messages", connection=engine.get_connection())
chat_history.add_user_message("Hello LangChain Postgres!")
chat_history.add_ai_message("Hi there!")
print(f"Chat history for session {session_id}: {chat_history.messages}")