falkordb-architecture-storage

Question

Is FalkorDB bound to ioredis, or is it flexible in the underlying database technology?

Answer Summary

FalkorDB is fundamentally bound to Redis - it is not a standalone database. It runs as a Redis module and cannot operate without Redis as the host platform. Here’s the key architecture:

Layer	Technology	Flexibility
Client Protocol	Redis protocol (port 6379)	✅ Flexible - use any Redis client (ioredis, redis-py, etc.)
Host Platform	Redis 7.4+	❌ Required - FalkorDB cannot run standalone
Graph Storage	GraphBLAS + CSC sparse matrices	❌ Internal to FalkorDB, not pluggable
Persistence	Redis RDB/AOF	❌ Tied to Redis persistence mechanisms

Architecture Deep Dive

1. FalkorDB as a Redis Module

┌─────────────────────────────────────────────────────────────┐
│                    Client Applications                       │
│   (ioredis, redis-py, redis-cli, any Redis client)         │
└─────────────────────┬───────────────────────────────────────┘
                      │ Redis Protocol (port 6379)
┌─────────────────────▼───────────────────────────────────────┐
│                     Redis 7.4+                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │            Redis Module API                            │ │
│  │  ┌──────────────────────────────────────────────────┐  │ │
│  │  │          FalkorDB Module                         │  │ │
│  │  │  - Custom Cypher commands (GRAPH.QUERY, etc.)   │  │ │
│  │  │  - GraphBLAS sparse matrix operations           │  │ │
│  │  │  - CSC format adjacency matrices                │  │ │
│  │  │  - Vector search indices                        │  │ │
│  │  └──────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  Redis provides:                                            │
│  - Networking & client connection handling                 │
│  - Memory management                                       │
│  - RDB/AOF persistence                                     │
│  - Replication & clustering                                │
└─────────────────────────────────────────────────────────────┘

2. Why Redis is Required

FalkorDB is not a standalone database. From the official documentation:

“FalkorDB is hosted by Redis, so you’ll first have to load it as a Module to a Redis server. Redis 7.4 is required for the latest FalkorDB version.”

Key dependencies on Redis:

Module API: FalkorDB extends Redis using the Redis Modules API to register custom commands (GRAPH.QUERY, GRAPH.DELETE, etc.)
Networking: Redis handles all client connections, protocol parsing, and command routing
Memory Management: Redis manages the in-memory data structures
Persistence: FalkorDB leverages Redis’s RDB and AOF persistence mechanisms
Replication: Redis clustering and replication features extend to FalkorDB data

3. GraphBLAS Storage Layer

Internal to FalkorDB:

GraphBLAS: Standard API for linear algebra operations on sparse matrices
CSC Format: Compressed Sparse Columns for adjacency matrix representation
In-Memory: Primary storage is RAM (inherited from Redis)
Disk Persistence: Through Redis RDB snapshots or AOF logs

Not Pluggable: The GraphBLAS storage implementation is internal to FalkorDB and cannot be swapped for alternative backends.

Client Protocol Flexibility

While FalkorDB requires Redis, you have full flexibility in client choice:

Supported Redis Clients

Language	Client Library	FalkorDB Compatible
Node.js	ioredis	✅ Yes
Node.js	node-redis	✅ Yes
Python	redis-py	✅ Yes
Python	aioredis	✅ Yes
Go	go-redis	✅ Yes
Java	Jedis	✅ Yes
Ruby	redis-rb	✅ Yes
CLI	redis-cli	✅ Yes

Why ioredis is used in our implementation:

From docs/lattice-opensource-setup/repo-initialization.md:86:

"dependencies": {
  "ioredis": "^5.4.2"
}

ioredis is a client library for Node.js/Bun to connect to Redis (and thus FalkorDB)
It’s not the underlying storage - it’s just the protocol client
You could swap ioredis for node-redis or any Redis-compatible client

Persistence Options

FalkorDB inherits Redis persistence mechanisms:

1. RDB (Redis Database)

Point-in-time snapshots at specified intervals
Binary format, compact storage
Faster restarts

2. AOF (Append Only File)

Logs every write operation
Can replay operations on restart
More durable, slightly slower

3. RDB + AOF

Combine both for maximum durability

4. No Persistence

Pure in-memory caching use case

Not disk-based by default: FalkorDB is designed for low-latency, in-memory operations with optional disk persistence for durability.

Alternatives to FalkorDB (Not FalkorDB Alternatives)

If you need different storage flexibility, consider these graph databases:

Database	Storage Architecture	Pluggable?
Neo4j	Custom disk-based storage	❌ Proprietary format
ArangoDB	RocksDB backend	✅ Can use RocksDB or memory
JanusGraph	Pluggable storage (HBase, Cassandra, BerkeleyDB)	✅ Highly flexible
Memgraph	In-memory (RocksDB for snapshots)	❌ Memory-first
FalkorDB	Redis module only	❌ Bound to Redis

Redis-Compatible Alternatives

If you want to replace Redis itself with alternatives:

1. Valkey (Redis Fork)

Open-source fork of Redis (post-license change)
Potential FalkorDB compatibility (untested)

2. KeyDB

Multi-threaded Redis fork
May support Redis modules

3. Disk-Based Redis Alternatives

These are NOT compatible with FalkorDB (different storage engines):

Project	Storage	Redis Protocol	FalkorDB Compatible?
SSDB	LevelDB	Partial	❌ No module support
Ardb	LevelDB/LMDB/KyotoCabinet	Yes	❌ No module support
Edis	LevelDB	Yes	❌ No module support

Conclusion: FalkorDB specifically requires Redis module API, so disk-based Redis alternatives won’t work.

Migration Path (If You Need Flexibility)

If you need a graph database with pluggable storage backends, you’ll need to migrate away from FalkorDB:

Option 1: JanusGraph

Supports HBase, Cassandra, BerkeleyDB
Can choose disk or distributed storage
More complex setup

Option 2: ArangoDB

Multi-model (graph + document)
RocksDB backend
Can run standalone or clustered

Option 3: Neo4j

Industry standard
Proprietary storage format
Commercial licensing for scale

Trade-off: These alternatives are slower than FalkorDB for GraphRAG workloads (FalkorDB is 280x faster than Neo4j for some operations).

Final Answer

Is FalkorDB bound to ioredis?

No - ioredis is just a client library. FalkorDB speaks the Redis protocol, so you can use:

ioredis (Node.js)
node-redis (Node.js)
redis-py (Python)
Any Redis-compatible client

Is FalkorDB flexible in the underlying database?

No - FalkorDB is fundamentally bound to Redis:

FalkorDB is a Redis module, not a standalone database
It requires Redis 7.4+ as the host platform
It cannot run on other databases (Postgres, MySQL, LevelDB, etc.)
The GraphBLAS storage layer is internal and not pluggable

Why This Design?

From the official docs:

“FalkorDB is going to target cases which require low latency and as such is going to be in memory.”

Benefits of Redis binding:

✅ Extremely fast (in-memory)
✅ Leverage Redis networking and client ecosystem
✅ Use Redis persistence mechanisms (RDB/AOF)
✅ Redis replication and clustering

Limitations:

❌ Must run Redis (can’t use Postgres, etc.)
❌ Primary storage is memory (with disk persistence)
❌ Bound to Redis licensing and ecosystem

Recommendations

Use FalkorDB when:

Low-latency GraphRAG is critical
You’re comfortable running Redis
In-memory + disk persistence is acceptable
You want Redis ecosystem compatibility

Consider alternatives when:

You need pluggable storage backends
Pure disk-based storage is required
Redis licensing is a concern
You need distributed graph storage (e.g., Cassandra)