buun-stack/falkordb/README.md

# FalkorDB

FalkorDB is a high-performance graph database with vector similarity search capabilities, designed for knowledge graphs and GraphRAG applications. It uses OpenCypher as its query language and is Redis-compatible.

## Table of Contents

- [Installation](#installation)
- [Prerequisites](#prerequisites)
- [Connection Information](#connection-information)
- [Usage](#usage)
- [Configuration](#configuration)
- [Cognee Integration](#cognee-integration)
- [Management](#management)
- [Troubleshooting](#troubleshooting)

## Installation

Install FalkorDB with interactive configuration:

```bash
just falkordb::install
```

This will:

- Create the `falkordb` namespace with Pod Security Standards (baseline)
- Generate and store a password in Vault (or Kubernetes Secret)
- Deploy FalkorDB using the custom Helm chart
- Optionally enable Prometheus monitoring

## Prerequisites

- Kubernetes cluster with Longhorn storage
- For secret management: Vault and External Secrets Operator (optional but recommended)
- For monitoring: kube-prometheus-stack (optional)

## Connection Information

| Property | Value                                 |
| -------- | ------------------------------------- |
| Host     | `falkordb.falkordb.svc.cluster.local` |
| Port     | `6379`                                |
| Protocol | Redis (Bolt not supported)            |

## Usage

### Get Password

```bash
just falkordb::get-password
```

### Health Check

Requires [telepresence](https://www.telepresence.io/) connection:

```bash
telepresence connect
just falkordb::health-check
```

### Test Graph Operations

Run a basic test that creates nodes, relationships, and queries:

```bash
just falkordb::test
```

### Redis CLI

Connect directly using redis-cli:

```bash
PASSWORD=$(just falkordb::get-password)
redis-cli -h falkordb.falkordb.svc.cluster.local -p 6379 -a "$PASSWORD"
```

### Cypher Queries

FalkorDB uses OpenCypher query language via Redis commands:

```bash
# Create a node
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph "CREATE (:Person {name: 'Alice', age: 30})"

# Create a relationship
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph \
  "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:KNOWS]->(b)"

# Query the graph
redis-cli -a "$PASSWORD" GRAPH.QUERY mygraph \
  "MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name, friend.name"

# Delete a graph
redis-cli -a "$PASSWORD" GRAPH.DELETE mygraph
```

### Python Client

```python
from falkordb import FalkorDB

db = FalkorDB(
    host='falkordb.falkordb.svc.cluster.local',
    port=6379,
    password='<password>'
)
graph = db.select_graph('knowledge')

# Create nodes
graph.query("CREATE (:Concept {name: 'Machine Learning'})")
graph.query("CREATE (:Concept {name: 'Neural Networks'})")

# Create relationship
graph.query("""
    MATCH (a:Concept {name: 'Neural Networks'}), (b:Concept {name: 'Machine Learning'})
    CREATE (a)-[:PART_OF]->(b)
""")

# Query
result = graph.query("MATCH (c:Concept) RETURN c.name")
for record in result.result_set:
    print(record)
```

## Configuration

### Environment Variables

| Variable               | Default     | Description             |
| ---------------------- | ----------- | ----------------------- |
| `FALKORDB_NAMESPACE`   | `falkordb`  | Kubernetes namespace    |
| `FALKORDB_VERSION`     | `v4.14.8`   | FalkorDB image version  |
| `FALKORDB_STORAGE_SIZE`| `8Gi`       | Persistent volume size  |

### Pod Security Standards

The namespace is configured with:

- `enforce=baseline` - Required for FalkorDB (runs as root)
- `warn=restricted` - Shows warnings for restricted violations

## Cognee Integration

FalkorDB can serve as both graph and vector store for [Cognee](https://github.com/topoteretes/cognee), enabling knowledge graph construction and RAG without separate vector database.

### Configuration

```bash
# .env for Cognee
GRAPH_DATABASE_PROVIDER=falkordb
GRAPH_DATABASE_URL=falkordb.falkordb.svc.cluster.local
GRAPH_DATABASE_PORT=6379

VECTOR_DB_PROVIDER=falkordb
VECTOR_DB_URL=falkordb.falkordb.svc.cluster.local
VECTOR_DB_PORT=6379
```

### Usage with Cognee

```python
import cognee

# Add documents
await cognee.add("documents/", dataset_name="knowledge_base")

# Generate knowledge graph (automatic)
await cognee.cognify()

# Search with RAG
results = await cognee.search("What is the relationship between X and Y?")
```

## Management

### Uninstall

```bash
just falkordb::uninstall
```

### Cleanup Vault Secrets

```bash
just falkordb::cleanup
```

### Available Commands

```bash
just falkordb                    # List all commands
just falkordb::install           # Install FalkorDB
just falkordb::uninstall         # Uninstall FalkorDB
just falkordb::get-password      # Get password
just falkordb::health-check      # Check health (requires telepresence)
just falkordb::test              # Run graph operation tests
just falkordb::cleanup           # Clean up Vault secrets
```

## Troubleshooting

### Pod Not Starting

Check pod status and logs:

```bash
kubectl get pods -n falkordb
kubectl logs falkordb-0 -n falkordb
kubectl describe pod falkordb-0 -n falkordb
```

### Authentication Issues

Verify password is correctly configured:

```bash
# Check secret exists
kubectl get secret falkordb-password -n falkordb

# Test authentication from within cluster
kubectl exec falkordb-0 -n falkordb -- redis-cli -a "$PASSWORD" PING
```

### Connection Refused

Ensure service is running:

```bash
kubectl get svc -n falkordb
```

For external access, use telepresence or port-forward:

```bash
kubectl port-forward svc/falkordb -n falkordb 6379:6379
```

### Memory Issues

FalkorDB stores graphs in memory. Monitor usage:

```bash
kubectl top pod -n falkordb
```

If running out of memory, increase limits in `falkordb-values.gomplate.yaml`.

## References

- [FalkorDB Documentation](https://docs.falkordb.com/)
- [FalkorDB GitHub](https://github.com/FalkorDB/FalkorDB)
- [OpenCypher Query Language](https://opencypher.org/)
- [Cognee Documentation](https://docs.cognee.ai/)