How to Set the URL for Your Vector Database in Cognee

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. 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 (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.

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) 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

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:

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:

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 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, 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.
• 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 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 will use the new URL.

Does Cognee validate the URL format before connecting?

The VectorConfig class in 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:

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

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

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