feat(falkordb): add production-ready test suite with 180 tests and benchmarks

docker/falkordb/.env

@@ -0,0 +1,16 @@
+# FalkorDB Docker Environment Configuration
+# Used by GraFlo for testing the FalkorDB connector
+
+# Container settings
+CONTAINER_NAME=graflo-falkordb
+IMAGE_VERSION=falkordb/falkordb:v4.14.10
+
+# Connection settings
+FALKORDB_HOST=localhost
+FALKORDB_PORT=6379
+
+# Authentication (optional - FalkorDB supports Redis AUTH)
+# FALKORDB_PASSWORD=
+
+# Default graph name for tests
+FALKORDB_DATABASE=testgraph

docker/falkordb/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+    falkordb:
+        image: ${IMAGE_VERSION}
+        restart: "no"
+        profiles: ["test.falkordb"]
+        ports:
+        -   "${FALKORDB_PORT}:6379"
+        container_name: ${CONTAINER_NAME}
+        volumes:
+        -   falkordb_data:/data
+
+volumes:
+    falkordb_data:

graflo/db/__init__.py

@@ -26,6 +26,7 @@
 from .arango.conn import ArangoConnection
 from .conn import Connection, ConnectionType
 from .connection import DBConfig, DBType
+from .falkordb.conn import FalkordbConnection
 from .manager import ConnectionManager
 from .neo4j.conn import Neo4jConnection
 from .postgres.conn import PostgresConnection
@@ -38,6 +39,7 @@
     "DBConfig",
     "ConnectionManager",
     "ArangoConnection",
+    "FalkordbConnection",
     "Neo4jConnection",
     "PostgresConnection",
     "TigerGraphConnection",

graflo/db/connection/config_mapping.py

@@ -4,6 +4,7 @@
     ArangoConfig,
     DBConfig,
     DBType,
+    FalkordbConfig,
     Neo4jConfig,
     PostgresConfig,
     TigergraphConfig,
@@ -14,5 +15,6 @@
     DBType.ARANGO: ArangoConfig,
     DBType.NEO4J: Neo4jConfig,
     DBType.TIGERGRAPH: TigergraphConfig,
+    DBType.FALKORDB: FalkordbConfig,
     DBType.POSTGRES: PostgresConfig,
 }

graflo/db/connection/onto.py

@@ -35,6 +35,7 @@ class DBType(StrEnum, metaclass=EnumMetaWithContains):
     ARANGO = "arango"
     NEO4J = "neo4j"
     TIGERGRAPH = "tigergraph"
+    FALKORDB = "falkordb"
 
     # Source databases (SQL, NoSQL)
     POSTGRES = "postgres"
@@ -55,6 +56,7 @@ def config_class(self) -> Type["DBConfig"]:
     DBType.ARANGO,  # Graph DBs can be sources
     DBType.NEO4J,  # Graph DBs can be sources
     DBType.TIGERGRAPH,  # Graph DBs can be sources
+    DBType.FALKORDB,  # Graph DBs can be sources
     DBType.POSTGRES,  # SQL DBs
     DBType.MYSQL,
     DBType.MONGODB,
@@ -66,6 +68,7 @@ def config_class(self) -> Type["DBConfig"]:
     DBType.ARANGO,
     DBType.NEO4J,
     DBType.TIGERGRAPH,
+    DBType.FALKORDB,
 }
 
 
@@ -607,6 +610,89 @@ def from_docker_env(
         return cls(**config_data)
 
 
+class FalkordbConfig(DBConfig):
+    """Configuration for FalkorDB connections.
+
+    FalkorDB is a Redis-based graph database that supports OpenCypher.
+    It stores graphs as Redis keys where each graph is a separate namespace.
+
+    FalkorDB structure: connection -> graph (Redis key) -> nodes/relationships
+    Unified model: connection -> schema -> entities
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="FALKORDB_",
+        case_sensitive=False,
+    )
+
+    def _get_default_port(self) -> int:
+        """Get default FalkorDB/Redis port."""
+        return 6379
+
+    def _get_effective_database(self) -> str | None:
+        """FalkorDB doesn't have a database level (connection -> graph -> nodes/relationships)."""
+        return None
+
+    def _get_effective_schema(self) -> str | None:
+        """For FalkorDB, 'database' field maps to schema (graph name) in unified model.
+
+        FalkorDB structure: connection -> graph (Redis key) -> nodes/relationships
+        Unified model: connection -> schema -> entities
+        """
+        return self.database
+
+    @classmethod
+    def from_docker_env(cls, docker_dir: str | Path | None = None) -> "FalkordbConfig":
+        """Load FalkorDB config from docker/falkordb/.env file.
+
+        The .env file structure may contain:
+        - FALKORDB_HOST: Hostname (defaults to localhost)
+        - FALKORDB_PORT: Port number (defaults to 6379)
+        - FALKORDB_PASSWORD: Redis AUTH password (optional)
+        - FALKORDB_DATABASE: Graph name (optional, can be set later)
+        """
+        if docker_dir is None:
+            docker_dir = (
+                Path(__file__).parent.parent.parent.parent / "docker" / "falkordb"
+            )
+        else:
+            docker_dir = Path(docker_dir)
+
+        env_file = docker_dir / ".env"
+        if not env_file.exists():
+            raise FileNotFoundError(f"Environment file not found: {env_file}")
+
+        # Load .env file manually
+        env_vars: Dict[str, str] = {}
+        with open(env_file, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    env_vars[key.strip()] = value.strip().strip('"').strip("'")
+
+        # Map environment variables to config
+        config_data: Dict[str, Any] = {}
+
+        # URI construction (FalkorDB uses redis:// protocol)
+        if "FALKORDB_URI" in env_vars:
+            config_data["uri"] = env_vars["FALKORDB_URI"]
+        else:
+            port = env_vars.get("FALKORDB_PORT", "6379")
+            hostname = env_vars.get("FALKORDB_HOST", "localhost")
+            config_data["uri"] = f"redis://{hostname}:{port}"
+
+        # Password (Redis AUTH)
+        if "FALKORDB_PASSWORD" in env_vars and env_vars["FALKORDB_PASSWORD"]:
+            config_data["password"] = env_vars["FALKORDB_PASSWORD"]
+
+        # Graph name (database in unified model)
+        if "FALKORDB_DATABASE" in env_vars:
+            config_data["database"] = env_vars["FALKORDB_DATABASE"]
+
+        return cls(**config_data)
+
+
 class PostgresConfig(DBConfig):
     """Configuration for PostgreSQL connections."""
 

graflo/db/falkordb/__init__.py

@@ -0,0 +1,25 @@
+"""FalkorDB connection implementation for graph database operations.
+
+This module implements the Connection interface for FalkorDB, providing
+specific functionality for graph operations in FalkorDB. FalkorDB is a
+Redis-based graph database that supports OpenCypher query language.
+
+Key Features:
+    - Label-based node organization (like Neo4j)
+    - Relationship type management
+    - Property indices
+    - Cypher query execution
+    - Batch node and relationship operations
+    - Redis-based storage with graph namespacing
+
+Example:
+    >>> from graflo.db.falkordb import FalkordbConnection
+    >>> from graflo.db.connection import FalkordbConfig
+    >>> config = FalkordbConfig(uri="redis://localhost:6379", database="mygraph")
+    >>> conn = FalkordbConnection(config)
+    >>> conn.init_db(schema, clean_start=True)
+"""
+
+from .conn import FalkordbConnection
+
+__all__ = ["FalkordbConnection"]