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

> Explore vector database options for Private-GPT including Qdrant, Chroma, Postgres, ClickHouse, and Milvus. Learn how to easily configure and set up your preferred backend.

- Repository: [Zylon/private-gpt](https://github.com/zylon-ai/private-gpt)
- Tags: how-to-guide
- Published: 2026-03-06

---

**Private-GPT supports five production-grade vector database backends—PostgreSQL, Chroma, Qdrant, Milvus, and ClickHouse—each configurable via a single [`settings.yaml`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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:

```bash

# 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`](https://github.com/zylon-ai/private-gpt/blob/main/settings.yaml) to select the database and provide connection parameters. The `vectorstore.database` key determines which configuration block is read.

#### PostgreSQL Configuration

```yaml
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

```yaml
vectorstore:
  database: chroma

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

```

#### Qdrant Configuration

```yaml
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

```yaml
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

```yaml
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:

```python
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`](https://github.com/zylon-ai/private-gpt/blob/main/settings.yaml).
- **Implementation details** are located in [`private_gpt/components/vector_store/vector_store_component.py`](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/components/vector_store/vector_store_component.py) (lines 40-162), with settings models defined in [`private_gpt/settings/settings.py`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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`](https://github.com/zylon-ai/private-gpt/blob/main/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.