Vector Database Options in Private-GPT: How to Configure Qdrant, Chroma, Postgres, ClickHouse, and Milvus

Private-GPT supports five production-grade vector database backends—PostgreSQL, Chroma, Qdrant, Milvus, and ClickHouse—each configurable via a single settings.yaml selector and installable through Poetry extras.

The zylon-ai/private-gpt repository abstracts all vector storage behind a unified VectorStoreComponent. By changing one configuration key and installing the corresponding dependency, you can switch from an in-memory Chroma instance to a distributed Qdrant or ClickHouse cluster without modifying application code.

How Private-GPT Abstracts Vector Database Options

The VectorStoreComponent acts as a singleton factory that reads settings.vectorstore.database and instantiates the appropriate concrete store. Located in private_gpt/components/vector_store/vector_store_component.py, the component handles dynamic imports, connection pooling, and LlamaIndex compatibility.

When initialized, the component:

1. Reads the selector from settings.vectorstore.database (defined in private_gpt/settings/settings.py lines 155-157).
2. Imports the required driver inside a try/except block. If the import fails, the error message instructs you to run poetry install --extras vector-stores-<db>.
3. Constructs the store using database-specific settings (host, port, credentials, collection names) parsed from Pydantic models such as PostgresSettings, QdrantSettings, MilvusSettings, and ClickHouseSettings (lines 88-199 in settings.py).
4. Exposes a retriever via get_retriever() that applies doc-id filtering for Qdrant and metadata filtering for other backends.

Because the component is decorated with @singleton, the same connection pool persists across the application lifecycle, preventing connection leaks in production deployments.

Supported Vector Database Backends

Private-GPT implements dedicated initialization logic for five vector stores. Each backend requires a specific Poetry extra and a corresponding configuration block in settings.yaml.

PostgreSQL with pgvector

PostgreSQL support leverages the pgvector extension. The component uses PGVectorStore from LlamaIndex, configured via PostgresSettings.

• Implementation: private_gpt/components/vector_store/vector_store_component.py lines 40-65
• Settings model: PostgresSettings (host, port, user, password, database, schema_name, table_name)
• Required extra: vector-stores-postgres

Chroma

Chroma runs embedded within the Private-GPT process using chromadb.PersistentClient. The repository includes a custom BatchedChromaVectorStore wrapper to optimize bulk inserts.

• Implementation: private_gpt/components/vector_store/vector_store_component.py lines 65-95
• Storage location: local_data/chroma_db (configurable via chroma.path)
• Required extra: vector-stores-chroma

Qdrant

Qdrant supports both REST and gRPC protocols. The component initializes QdrantClient and wraps it in QdrantVectorStore, enabling hybrid search and payload filtering.

• Implementation: private_gpt/components/vector_store/vector_store_component.py lines 96-124
• Settings model: QdrantSettings (host, port, grpc_port, prefer_grpc, url, api_key)
• Required extra: vector-stores-qdrant

Milvus

Milvus integration supports both Milvus Lite (local file) and full Milvus servers. The component uses MilvusVectorStore from LlamaIndex with automatic collection management.

• Implementation: private_gpt/components/vector_store/vector_store_component.py lines 125-162
• Settings model: MilvusSettings (uri, collection_name, overwrite, token, user, password)
• Required extra: vector-stores-milvus

ClickHouse

ClickHouse vector storage uses the clickhouse-connect driver with the ClickHouseVectorStore implementation, suitable for high-throughput analytics workloads.

• Implementation: private_gpt/components/vector_store/vector_store_component.py lines 63-90
• Settings model: ClickHouseSettings (host, port, username, password, database, table_name, secure)
• Required extra: vector-stores-clickhouse

Installation and Configuration

Installing Vector Store Dependencies

Private-GPT uses Poetry extras to keep the base installation lightweight. Install only the drivers you need:

# PostgreSQL with pgvector

poetry install --extras vector-stores-postgres

# Chroma (embedded, no external server required)

poetry install --extras vector-stores-chroma

# Qdrant

poetry install --extras vector-stores-qdrant

# Milvus

poetry install --extras vector-stores-milvus

# ClickHouse

poetry install --extras vector-stores-clickhouse

Configuring settings.yaml

Create or modify your settings.yaml to select the database and provide connection parameters. The vectorstore.database key determines which configuration block is read.

PostgreSQL Configuration

vectorstore:
  database: postgres

postgres:
  host: localhost
  port: 5432
  user: postgres
  password: postgres
  database: private_gpt
  schema_name: public
  table_name: embeddings

embedding:
  embed_dim: 384  # Must match your embedding model dimension

Chroma Configuration

vectorstore:
  database: chroma

chroma:
  path: local_data/chroma_db  # Optional; defaults to local_data/chroma_db

Qdrant Configuration

vectorstore:
  database: qdrant

qdrant:
  host: localhost
  port: 6333
  grpc_port: 6334
  prefer_grpc: false
  # For remote Qdrant Cloud:

  # url: https://your-cluster.cloud.qdrant.io

  # api_key: your-api-key

Milvus Configuration

vectorstore:
  database: milvus

milvus:
  uri: local_data/private_gpt/milvus/milvus_local.db  # Milvus Lite path

  collection_name: my_documents
  overwrite: true
  # For Zilliz Cloud or self-hosted Milvus:

  # uri: http://localhost:19530

  # token: root:Milvus

ClickHouse Configuration

vectorstore:
  database: clickhouse

clickhouse:
  host: localhost
  port: 8443
  username: default
  password: ""
  database: __default__
  table_name: embeddings
  secure: true

Programmatic Usage

While Private-GPT typically manages the vector store through dependency injection, you can instantiate the component directly for testing or custom scripts:

from private_gpt.settings.settings import Settings, settings
from private_gpt.components.vector_store.vector_store_component import VectorStoreComponent

# Load configuration (normally injected by the framework)

cfg: Settings = settings()

# Initialize the component - automatically selects the configured database

vector_component = VectorStoreComponent(cfg)

# Access the underlying store (e.g., for manual embedding insertion)

vector_component.vector_store.add(
    vectors=[[0.1] * 384],  # Match your embedding dimension

    ids=["doc-001"],
    documents=["Sample document content"],
    metadatas=[{"source": "manual_upload"}],
)

# Create a retriever with metadata filtering

retriever = vector_component.get_retriever(index=None)
results = retriever.retrieve("query text")
for node in results:
    print(f"ID: {node.id}, Score: {node.score}")

The VectorStoreComponent exposes a get_retriever() method that returns a LlamaIndex-compatible retriever with built-in support for doc-id filtering (Qdrant) and metadata filtering (other stores).

Summary

• Private-GPT provides a unified interface for five vector database options through the VectorStoreComponent singleton.
• Supported backends: PostgreSQL (pgvector), Chroma (embedded), Qdrant, Milvus, and ClickHouse.
• Configuration requires only two steps: install the appropriate Poetry extra (vector-stores-<db>) and set the vectorstore.database selector in settings.yaml.
• Implementation details are located in private_gpt/components/vector_store/vector_store_component.py (lines 40-162), with settings models defined in private_gpt/settings/settings.py.
• Runtime behavior includes automatic connection pooling, lazy imports with clear error messages for missing dependencies, and metadata-aware retrieval interfaces.

Frequently Asked Questions

How do I switch from Chroma to PostgreSQL in Private-GPT?

Change the vectorstore.database value from chroma to postgres in your settings.yaml, install the PostgreSQL driver with poetry install --extras vector-stores-postgres, and provide the connection details under the postgres: configuration block. The VectorStoreComponent automatically instantiates PGVectorStore on the next startup.

What is the default vector database if I don't specify one?

If no vector database is explicitly configured, Private-GPT defaults to Chroma using an embedded persistent client that stores data in local_data/chroma_db. This requires no external server and works out-of-the-box after installing the vector-stores-chroma extra.

Can I use Milvus Lite instead of a full Milvus server?

Yes. Set the milvus.uri configuration to a local file path ending in .db (e.g., local_data/private_gpt/milvus/milvus_local.db). When the URI points to a local file, Milvus runs in Lite mode as an embedded library. For production deployments, change the URI to http://localhost:19530 or your Zilliz Cloud endpoint.

Where does Private-GPT handle connection errors for missing vector store drivers?

Connection and import errors are handled in private_gpt/components/vector_store/vector_store_component.py. Each database initialization block (lines 40-162) wraps the third-party import in a try/except statement. If the import fails, the component raises a ValueError with instructions to install the specific Poetry extra (e.g., poetry install --extras vector-stores-qdrant), ensuring clear troubleshooting paths for deployment issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}