falkordb-ex

Elixir client for FalkorDB 4.18.3 built on top of Redix. V1 supports single-node and sentinel topologies.

Supported FalkorDB deployments

• Single-node / standalone FalkorDB (mode: :single) via URL or host/port.
• Sentinel-managed FalkorDB (mode: :sentinel) via sentinel endpoints and group name.
• Current V1 scope does not include Redis Cluster mode.

Installation

Add :falkordb to your dependencies:

def deps do
  [
    {:falkordb, "~> 0.1.0"}
  ]
end

Quick start

{:ok, db} =
  FalkorDB.connect(
    mode: :single,
    url: "redis://127.0.0.1:6379"
  )

graph = FalkorDB.select_graph(db, "social")

{:ok, _} = FalkorDB.Graph.query(graph, "CREATE (:Person {name: 'Alice'})")
{:ok, result} = FalkorDB.Graph.ro_query(graph, "MATCH (n:Person) RETURN n.name AS name")

IO.inspect(result.data)
:ok = FalkorDB.stop(db)

Sentinel

{:ok, db} =
  FalkorDB.connect(
    mode: :sentinel,
    group: "mymaster",
    sentinels: [{"127.0.0.1", 26_379}, {"127.0.0.1", 26_380}]
  )

API coverage

The client includes wrappers for the FalkorDB 4.18.3 module command surface:

• Query: GRAPH.QUERY, GRAPH.RO_QUERY, GRAPH.EXPLAIN, GRAPH.PROFILE
• Graph ops: GRAPH.DELETE, GRAPH.COPY, GRAPH.RESTORE, GRAPH.EFFECT, GRAPH.BULK
• Schema/admin: GRAPH.CONSTRAINT, GRAPH.SLOWLOG, GRAPH.MEMORY, GRAPH.CONFIG, GRAPH.LIST, GRAPH.INFO
• Advanced/admin: GRAPH.DEBUG, GRAPH.UDF Compact parsing includes graph entities and temporal types (datetime, date, time, duration).

Additional API behavior:

• FalkorDB.config_set/2 supports setting multiple options in one call via keyword lists or maps, matching GRAPH.CONFIG SET <NAME> <VALUE> [<NAME> <VALUE> ...].
• FalkorDB.Graph.explain/3 and FalkorDB.Graph.profile/3 accept the same query option style as query/3 (for example timeout and version).
• FalkorDB.Graph.memory_usage/2 normalizes responses into a stable map shape across RESP2/RESP3.

Test coverage

Test coverage includes both fast unit tests and opt-in integration tests:

• Unit tests cover command dispatch/building, query parameter serialization, compact parser behavior, and schema cache metadata resolution paths.
• Standalone integration tests cover end-to-end query flow (nodes/edges/paths), temporal values, UDF lifecycle, and indexing/search flows including vector, full-text, and geospatial queries.
• Sentinel integration tests cover connecting through sentinel and executing graph commands in sentinel mode.

Quality checks

Run local checks:

mix check

mix check runs:

• mix format --check-formatted
• mix credo --strict
• mix test

Integration tests

Integration tests are opt-in and disabled by default. To run them:

FALKORDB_RUN_INTEGRATION=1 mix test

Standalone

Environment:

• FALKORDB_URL (default: redis://127.0.0.1:6379)
• FALKORDB_TEST_GRAPH (default: elixir-test) Coverage highlights:
• graph CRUD/query execution and compact parsing
• temporal values (date, time, datetime, duration)
• UDF load/list/query/delete/flush flows
• index creation and search (VECTOR, FULLTEXT, geospatial RANGE)

Sentinel

Environment:

• FALKORDB_SENTINELS (comma-separated host:port, example: 127.0.0.1:26379,127.0.0.1:26380)
• FALKORDB_SENTINEL_GROUP (default: mymaster) Coverage highlights:
• sentinel discovery and connection
• query/list command flow against sentinel-managed deployment

Examples

Runnable scripts are available under examples/:

• examples/quickstart.exs
• examples/sentinel.exs

Release

This repo includes:

• CI workflow: .github/workflows/ci.yml
• Hex release workflow: .github/workflows/release.yml Set HEX_API_KEY in repository secrets before publishing tags (for example v0.1.0).