langchain-cockroachdb

LangChain integration for CockroachDB with native vector support

Quick Start • Features • Documentation • Examples • Contributing

Overview

Build LLM applications with CockroachDB's distributed SQL database and native vector search capabilities. This integration provides:

• 🎯 Native Vector Support - CockroachDB's VECTOR type
• 🚀 C-SPANN Indexes - Distributed vector indexes optimized for scale
• 🔄 Automatic Retries - Retries transient CockroachDB errors (40001, 40003, 08xxx, 57P01, 58C00, 58C01) on every operation
• ⚡ Async & Sync APIs - Choose based on your use case
• 🏗️ Distributed by Design - Built for CockroachDB's architecture

Quick Start

Installation

pip install langchain-cockroachdb

Basic Usage

import asyncio
from langchain_cockroachdb import AsyncCockroachDBVectorStore, CockroachDBEngine
from langchain_openai import OpenAIEmbeddings

async def main():
    # Initialize
    engine = CockroachDBEngine.from_connection_string(
        "cockroachdb://user:pass@host:26257/db"
    )
    
    await engine.ainit_vectorstore_table(
        table_name="documents",
        vector_dimension=1536,
    )
    
    vectorstore = AsyncCockroachDBVectorStore(
        engine=engine,
        embeddings=OpenAIEmbeddings(),
        collection_name="documents",
    )
    
    # Add documents
    await vectorstore.aadd_texts([
        "CockroachDB is a distributed SQL database",
        "LangChain makes building LLM apps easy",
    ])
    
    # Search
    results = await vectorstore.asimilarity_search(
        "Tell me about databases",
        k=2
    )
    
    for doc in results:
        print(doc.page_content)
    
    await engine.aclose()

asyncio.run(main())

Long-Term Memory for LangGraph

CockroachDBStore gives LangGraph agents memory that every thread can read, with semantic search and expiry:

from langchain_cockroachdb import CockroachDBStore
from langchain_openai import OpenAIEmbeddings

with CockroachDBStore.from_conn_string(
    "cockroachdb://user:pass@host:26257/db",
    pool_config={"max_size": 10},
    index={"dims": 1536, "embed": OpenAIEmbeddings(model="text-embedding-3-small")},
    ttl={"default_ttl": 60 * 24 * 30},  # minutes
) as store:
    store.setup()
    store.put(("user", "alice", "memories"), "seat", {"text": "Prefers window seats"})
    results = store.search(("user", "alice"), query="Where does Alice like to sit?")
    # Pass store=store to create_agent, StateGraph.compile or create_deep_agent

See the Long-Term Memory guide.

Features

Vector Store

• Native VECTOR type support with C-SPANN indexes
• Advanced metadata filtering ($and, $or, $gt, $in, etc.)
• Hybrid search (full-text + vector similarity)
• Multi-tenancy with namespace-based isolation and C-SPANN prefix columns

Chat History

• Persistent conversation storage in CockroachDB
• Session management by thread ID
• Drop-in replacement for other LangChain chat history implementations

LangGraph Checkpointer

• Short-term memory for multi-turn LangGraph agents
• Human-in-the-loop with interrupt/resume support
• Both CockroachDBSaver (sync) and AsyncCockroachDBSaver
• Compatible with LangGraph's compile(checkpointer=...) interface

LangGraph Long-Term Memory Store

• Memory that every thread can read, for LangGraph agents and Deep Agents
• Both CockroachDBStore (sync) and AsyncCockroachDBStore, with the API of LangGraph's PostgresStore
• Semantic search on a C-SPANN vector index, with metadata filters
• Expiry through CockroachDB row-level TTL, with no sweeper thread
• delete_namespace deletes a user's memories in one transaction

Reliability and Retries

• Retries transient CockroachDB errors (40001, 40003, 08xxx, 57P01, 58C00, 58C01, 53300) on every operation
• Configurable RetryPolicy with exponential backoff, jitter and optional hang guards
• Idempotent writes (UPSERTs, ON CONFLICT DO NOTHING) for safe retries
• Connection pooling with health checks and pre-ping
• Works with both SERIALIZABLE (default, recommended) and READ COMMITTED isolation
• See the Retries and Resilience guide

Developer Experience

• Async-first design for high concurrency
• Sync wrapper for simple scripts
• Type-safe with full type hints
• Comprehensive test suite (177 tests)

Documentation

📚 Complete Documentation

LangChain Official Integration Docs:

• CockroachDB Provider
• CockroachDB Vector Store
• CockroachDB Chat Message History

Getting Started:

• Installation
• Quick Start
• Configuration

Guides:

• Vector Store
• Vector Indexes
• Hybrid Search
• Chat History
• Multi-Tenancy
• LangGraph Checkpointer
• LangGraph Long-Term Memory
• Async vs Sync
• Retries and Resilience

Examples

🔧 Working Examples

• quickstart.py - Get started in 5 minutes
• sync_usage.py - Synchronous API
• vector_indexes.py - Index optimization
• hybrid_search.py - FTS + vector search
• metadata_filtering.py - Advanced queries
• chat_history.py - Persistent conversations
• checkpointer.py - LangGraph checkpointer
• long_term_memory.py - LangGraph long-term memory store
• multi_tenancy.py - Namespace-based multi-tenancy
• retry_configuration.py - Configuration patterns

Development

Setup

# Clone repository
git clone https://github.com/cockroachdb/langchain-cockroachdb.git
cd langchain-cockroachdb

# Install dependencies
pip install -e ".[dev]"

# Start CockroachDB
docker-compose up -d

# Run tests
make test

Documentation

# Install docs dependencies
pip install -e ".[docs]"

# Serve documentation locally
mkdocs serve

# Open http://127.0.0.1:8000

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Why CockroachDB?

• Distributed SQL - Scale horizontally across regions
• Native Vector Support - First-class VECTOR type and C-SPANN indexes
• Strong Consistency - SERIALIZABLE isolation by default, READ COMMITTED also supported
• Cloud Native - Deploy anywhere (IBM, AWS, GCP, Azure, on-prem)
• PostgreSQL Compatible - Familiar SQL with distributed superpowers

Links

• GitHub Repository
• PyPI Package
• CockroachDB Documentation
• LangChain Documentation
• Report Issues

License

Apache License 2.0 - see LICENSE for details.

Acknowledgments

Built for the CockroachDB and LangChain communities.

• CockroachDB - Distributed SQL database
• LangChain - LLM application framework