# How to Set the URL for Your Vector Database in Cognee

> Easily set your Cognee vector database URL at runtime using cognee.config.set_vector_db_url() without restarting your application.

- Repository: [Topoteretes/cognee](https://github.com/topoteretes/cognee)
- Tags: how-to-guide
- Published: 2026-03-16

---

**Call `cognee.config.set_vector_db_url()` with your endpoint string to configure the vector database connection at runtime without restarting your application.**

Cognee, an open-source knowledge graph framework (topoteretes/cognee), stores vector database configuration in a centralized `VectorConfig` object. Whether you are connecting to ChromaDB, PGVector, or Neptune Analytics, you need to set the URL for your vector database in Cognee to ensure the embedding lookup layer points to the correct instance.

## Understanding the VectorConfig Architecture

The vector database URL is managed by the **`VectorConfig`** class defined in [`cognee/infrastructure/databases/vector/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/config.py). This configuration object stores the **`vector_db_url`** field, which holds the connection string for your chosen provider.

When components need access to vector storage, they call `get_vectordb_config()` or the context-aware `get_vectordb_context_config()`. These functions return a singleton instance of `VectorConfig`, ensuring that URL changes propagate immediately throughout the framework.

## Runtime Configuration with set_vector_db_url()

To set the URL for your vector database in Cognee at runtime, use the public API method `set_vector_db_url()` available on the `cognee.config` namespace.

According to the source code in [`cognee/api/v1/config/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/config/config.py) (lines 182-185), this method fetches the singleton `VectorConfig` instance via `get_vectordb_config()` and overwrites the `vector_db_url` attribute with your supplied string.

```python
import cognee

# Set your vector database endpoint

cognee.config.set_vector_db_url("http://localhost:8000")

```

The `VectorConfig` validator (lines 38-52 in [`cognee/infrastructure/databases/vector/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/config.py)) normalizes relative paths to absolute ones but preserves URL strings unchanged, allowing HTTP(S) endpoints, database connection strings, and special URIs like `neptune-graph://`.

## Provider-Specific URL Formats

Different vector database providers require specific URL formats. Cognee supports the following patterns:

- **ChromaDB (Local Server)**: `http://localhost:8000`
- **PGVector (PostgreSQL)**: `postgresql://user:password@host:5432/dbname`
- **Neptune Analytics**: `neptune-graph://my-graph-id`
- **LanceDB (Embedded)**: `/absolute/path/to/cognee.lancedb`

## Practical Implementation Examples

### Connecting to a Remote ChromaDB Instance

```python
import cognee

# Point to a running ChromaDB server

cognee.config.set_vector_db_url("http://chromadb.mycompany.com:8000")

# Verify configuration

config = cognee.get_vectordb_config()
print(config.vector_db_url)  # Output: http://chromadb.mycompany.com:8000

```

### Configuring PGVector with Authentication

First set the provider, then the URL:

```python
import cognee

cognee.config.set_vector_db_provider("pgvector")
cognee.config.set_vector_db_url(
    "postgresql://cognee_user:secret@db.myhost.com:5432/cognee_vectors"
)

# Initialize engine to verify connection

from cognee.infrastructure.databases.vector import get_vector_engine
engine = get_vector_engine()

```

### Switching Endpoints Dynamically

You can change the vector database URL without restarting your application:

```python
import cognee

# Development environment

cognee.config.set_vector_db_url("http://dev-chroma:8000")

# Later, switch to production

cognee.config.set_vector_db_url("http://prod-chroma:8000")

```

## How the Configuration Propagates

When you call `set_vector_db_url()`, the change affects all subsequent vector engine creations. The [`create_vector_engine.py`](https://github.com/topoteretes/cognee/blob/main/create_vector_engine.py) module (located in `cognee/infrastructure/databases/vector/`) consumes this URL to instantiate the concrete backend handler.

For CLI users, the same functionality is exposed via [`cognee/cli/commands/config_command.py`](https://github.com/topoteretes/cognee/blob/main/cognee/cli/commands/config_command.py), allowing you to run `cognee config set_vector_db_url <url>` from the terminal.

## Summary

- **Runtime Configuration**: Use `cognee.config.set_vector_db_url()` to update the connection string without environment file edits.
- **Singleton Pattern**: Changes apply immediately via the `VectorConfig` singleton in [`cognee/infrastructure/databases/vector/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/config.py).
- **Format Flexibility**: Supports HTTP URLs, PostgreSQL connection strings, Neptune graph URIs, and file system paths.
- **Dynamic Switching**: Modify endpoints on-the-fly for multi-environment workflows.
- **Engine Integration**: The [`create_vector_engine.py`](https://github.com/topoteretes/cognee/blob/main/create_vector_engine.py) module uses this URL to initialize the correct vector database handler.

## Frequently Asked Questions

### Can I set the vector database URL via environment variables?

While Cognee supports environment-based configuration for some settings, the recommended approach to set the URL for your vector database is using `cognee.config.set_vector_db_url()` at runtime. This method updates the `VectorConfig` singleton directly, ensuring immediate propagation without requiring application restarts.

### What happens if I change the URL after initializing the vector engine?

The `VectorConfig` object stores the URL centrally. Any component calling `get_vectordb_config()` or `get_vectordb_context_config()` receives the updated value. However, existing vector engine instances may retain their original connection; new engine instances created via [`create_vector_engine.py`](https://github.com/topoteretes/cognee/blob/main/create_vector_engine.py) will use the new URL.

### Does Cognee validate the URL format before connecting?

The `VectorConfig` class in [`cognee/infrastructure/databases/vector/config.py`](https://github.com/topoteretes/cognee/blob/main/cognee/infrastructure/databases/vector/config.py) validates and normalizes paths, converting relative paths to absolute ones. URL strings are passed through unchanged to the underlying provider, which handles connection validation when the vector engine initializes.

### How do I verify the current vector database URL configuration?

Access the `vector_db_url` attribute directly from the configuration object:

```python
import cognee
config = cognee.get_vectordb_config()
print(config.vector_db_url)

```

This returns the active URL string currently stored in the singleton instance.