Concurrent reads</th>	Pooled (mean)</th>	Multiplexed (mean)</th>	Speedup</th></tr></thead>
1</td>	315.3 µs</td>	384.3 µs</td>	0.82×</td></tr>
8</td>	815.0 µs</td>	862.7 µs</td>	0.94×</td></tr>
64</td>	5.58 ms</td>	3.69 ms</td>	1.51×</td></tr>
256</td>	20.43 ms</td>	11.85 ms</td>	1.72×</td></tr> </tbody> </table> Measured 2026-06-24 · Darwin arm64, Apple M1 Pro · FalkorDB falkordb/falkordb@sha256:e4b43a2c5231e3c96b8dccec3d6b0f212e057435f4dc0fd63d73b642a20f958d</code> · criterion 0.8 · commit d47fc61</code>. Reproduce with just bench</code>. </figcaption> </figure> Read that table honestly:</p> At concurrency 1, pooling wins.</strong> One query at a time has nothing to multiplex, and the multiplexer's bookkeeping is pure overhead. The speedup is below</em> 1.0 — multiplexing is slightly slower here, and pretending otherwise would be lying to you.</li> As concurrency climbs, multiplexing pulls ahead.</strong> By 64 concurrent reads it's ~1.5× faster, and by 256 it's ~1.7×, because the pooled strategy is serializing waves of queries through 8 exclusive connections while the multiplexer keeps many commands in flight per socket.</li> </ul> So the guidance writes itself: a request/response app doing one query at a time? Pooled is simple and great. A server fanning out hundreds of concurrent graph reads? Multiplex. The default for the async client is multiplexed with 8 sockets, which is the right call for the server workloads people actually point this at.</p> The harness, by the way, skips itself cleanly when no server is reachable, so it stays runnable in CI without flaking — a small thing I care about a lot, and the subject of more than one bug fix.</p> You can reproduce the table with just bench</code> against your own server; your numbers will differ, which is exactly why they're labeled with the machine and date. Next up, the feature that means you don't even need a server running to try any of this: the embedded FalkorDB</a>.</p> Rows that don't lie: header-aware, fallible result iteration Barak — Tue, 09 Jun 2026 00:00:00 +0000 In Part 2</a> we made the data going in</em> honest. This post is about the data coming out</em>.</p> The old result API had two original sins, and if you've used a database driver in a dynamically-typed mood you'll recognize both: you addressed columns by position</strong> (row[0]</code>, row[1]</code> — good luck when someone reorders the RETURN</code>), and a value that didn't match your expectation tended to surface as a panic somewhere deep in iteration. Both of those are the kind of bug that passes code review and then pages you at 2am.</p> The new shape</h2> Two changes, and they compose:</p> Result sets are header-aware.</strong> A row knows its column names, so you read by alias — row.try_get("year")</code> — not by a magic index.</li> Iteration is fallible.</strong> The result stream yields FalkorResult<Row></code>. A row that fails to parse is a real Err</code> you can ?</code>, not a landmine.</li> </ol> Here's the real examples/rows.rs</code>:</p> /</span></span> Copyright FalkorDB Ltd. 2023 - present</span></span> * Licensed under the MIT License.</span></span> /</span></span> </span> //</span>! Header-aware result rows: reading columns by name or index, with strict typed access.</span></span> //</span>!</span></span> //</span>! Run with: `cargo run --example rows`</span></span> //</span>!</span></span> //</span>! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`).</span></span> </span> use</span> falkordb</span>::</span>{</span>FalkorClientBuilder</span>,</span> FalkorConnectionInfo</span>,</span> FalkorValue</span>}</span>;</span></span> </span> fn</span> main</span>(</span>)</span> -></span> Result</span><</span>(</span>)</span>,</span> Box</span><</span>dyn</span> std</span>::</span>error</span>::</span>Error</span>></span>></span> {</span></span> let</span> connection_info</span>:</span> FalkorConnectionInfo</span> =</span> "</span>falkor://127.0.0.1:6379</span>"</span>.</span>try_into</span>(</span>)</span>?</span>;</span></span> let</span> client</span> =</span> FalkorClientBuilder</span>::</span>new</span>(</span>)</span></span> .</span>with_connection_info</span>(</span>connection_info</span>)</span></span> .</span>build</span>(</span>)</span>?</span>;</span></span> </span> let</span> mut</span> graph</span> =</span> client</span>.</span>select_graph</span>(</span>"</span>rows_example</span>"</span>)</span>;</span></span> </span> //</span> Start from a clean slate so the example is idempotent across runs.</span></span> let</span> _</span> =</span> graph</span>.</span>delete</span>(</span>)</span>;</span></span> </span> graph</span></span> .</span>query</span>(</span></span> "</span>CREATE (:Movie </span>{</span>title: 'The Matrix', year: 1999, rating: 8.7</span>}</span>),</span></span> (:Movie </span>{</span>title: 'Heat', year: 1995, rating: 8.3</span>}</span>)</span>"</span>,</span></span> )</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> </span> //</span> ── Read columns by alias, converted to the type you ask for ────────────</span></span> let</span> mut</span> result</span> =</span> graph</span></span> .</span>query</span>(</span></span> "</span>MATCH (m:Movie)</span></span> RETURN m.title AS title, m.year AS year, m.rating AS rating</span></span> ORDER BY m.year</span>"</span>,</span></span> )</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> </span> //</span> `data` yields `FalkorResult<Row>`, so a row that fails to parse is a real `Err` you can `?`.</span></span> for</span> row</span> in</span> result</span>.</span>data</span>.</span>by_ref</span>(</span>)</span> {</span></span> let</span> row</span> =</span> row</span>?</span>;</span></span> let</span> title</span>:</span> String</span> =</span> row</span>.</span>try_get</span>(</span>"</span>title</span>"</span>)</span>?</span>;</span></span> let</span> year</span>:</span> i64</span> =</span> row</span>.</span>try_get</span>(</span>"</span>year</span>"</span>)</span>?</span>;</span></span> let</span> rating</span>:</span> f64</span> =</span> row</span>.</span>try_get</span>(</span>"</span>rating</span>"</span>)</span>?</span>;</span></span> println!</span>(</span>"</span>{</span>title</span>}</span> (</span>{</span>year</span>}</span>) — rated </span>{</span>rating</span>}</span>"</span>)</span>;</span></span> }</span></span> </span> //</span> ── Read by index, and borrow the raw value without converting ──────────</span></span> let</span> mut</span> counted</span> =</span> graph</span>.</span>query</span>(</span>"</span>MATCH (m:Movie) RETURN count(m)</span>"</span>)</span>.</span>execute</span>(</span>)</span>?</span>;</span></span> if</span> let</span> Some</span>(</span>row</span>)</span> =</span> counted</span>.</span>data</span>.</span>next</span>(</span>)</span> {</span></span> let</span> row</span> =</span> row</span>?</span>;</span></span> let</span> count</span>:</span> i64</span> =</span> row</span>.</span>try_get_at</span>(</span>0</span>)</span>?</span>;</span></span> println!</span>(</span>"</span>movies: </span>{</span>count</span>}</span>"</span>)</span>;</span></span> //</span> `get_at` borrows the underlying `FalkorValue` without converting or cloning.</span></span> assert_eq!</span>(</span>row</span>.</span>get_at</span>(</span>0</span>)</span>,</span> Some</span>(</span>&</span>FalkorValue</span>::</span>I64</span>(</span>count</span>)</span>)</span>)</span>;</span></span> }</span></span> </span> //</span> ── Collect a whole result set; `collect` short-circuits on the first error ──</span></span> let</span> titles</span>:</span> Vec</span><</span>String</span>></span> =</span> graph</span></span> .</span>query</span>(</span>"</span>MATCH (m:Movie) RETURN m.title AS title ORDER BY m.title</span>"</span>)</span></span> .</span>execute</span>(</span>)</span>?</span></span> .</span>data</span></span> .</span>map</span>(</span>\|</span>row</span>\|</span> row</span>?</span>.</span>try_get</span>::</span><</span>String</span>></span>(</span>"</span>title</span>"</span>)</span>)</span></span> .</span>collect</span>::</span><</span>Result</span><</span>_</span>,</span> _</span>></span>></span>(</span>)</span>?</span>;</span></span> println!</span>(</span>"</span>titles: </span>{</span>titles:?</span>}</span>"</span>)</span>;</span></span> </span> //</span> ── Turn a row into a column -> value map ───────────────────────────────</span></span> let</span> mut</span> as_map</span> =</span> graph</span></span> .</span>query</span>(</span>"</span>MATCH (m:Movie) RETURN m.title AS title, m.year AS year ORDER BY m.year LIMIT 1</span>"</span>)</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> if</span> let</span> Some</span>(</span>row</span>)</span> =</span> as_map</span>.</span>data</span>.</span>next</span>(</span>)</span> {</span></span> let</span> map</span> =</span> row</span>?</span>.</span>into_map</span>(</span>)</span>;</span></span> println!</span>(</span>"</span>oldest movie as a map: </span>{</span>map:?</span>}</span>"</span>)</span>;</span></span> }</span></span> </span> graph</span>.</span>delete</span>(</span>)</span>?</span>;</span></span> Ok</span>(</span>(</span>)</span>)</span></span> }</span></span></code></pre>Source: examples/rows.rs</code></a> — compiled in CI.</p> Why FalkorResult<Row></code> is the important part</h2> Look at the iterator item type. It's not Row</code>, it's FalkorResult<Row></code>. That one decision ripples outward in the nicest way:</p> ?</code> works mid-iteration.</strong> let row = row?;</code> and the unhappy path is handled the same way you handle every other error in Rust. No special "did this row secretly fail?" dance.</li> collect</code> short-circuits.</strong> Collecting into a Result<Vec<_>, _></code> stops at the first bad row and hands you the error. One malformed value doesn't get silently dropped or turned into a default.</li> Typed access is explicit.</strong> try_get::<i64>("year")</code> says exactly what you expect, and converts in one step. If the column is actually a string, you get an Err</code> describing the mismatch — at the call site, where you can do something about it.</li> </ul> And when you don't</em> want to convert, get_at</code> borrows the raw FalkorValue</code> without cloning, so the escape hatch is there when you need to inspect the wire value directly. Ergonomics shouldn't cost you control.</p> The "by name" thing is not a small thing</h2> I want to dwell on reading columns by alias for a second, because it's the feature that quietly prevents the most bugs. Positional access couples your Rust code to the order</em> of your RETURN</code> clause. The day someone adds a column, or reorders two for readability, every positional index downstream is now silently pointing at the wrong data — and nothing fails, it just returns nonsense. Reading row.try_get("year")</code> is immune to that. The query can grow and shuffle; your code keeps asking for year</code> and keeps getting year</code>.</p> There's also a tidy into_map()</code> when you genuinely want the whole row as a column → value</code> map — handy for logging or for shoving a row into something generic.</p> This is about as far as the untyped</em> row API goes. The natural next question is "can I skip the per-column try_get</code> and just deserialize a row into my own struct?" Yes — that's the serde</code> story in Part 6</a>. But first, the feature I had the most fun building: making the whole thing async and streaming</strong>.</p> Stop hand-quoting Cypher: type-safe, injection-proof parameters Barak — Sat, 06 Jun 2026 00:00:00 +0000 Every database client eventually has the same coming-of-age moment: the day it stops letting you build queries with string concatenation. Today's the day for this one.</p> The bad old way</h2> Here's the shape of code I never want to write again — and rather than hand-type it (this blog has a rule: no uncompiled Rust), I'll point you at the commented-out "before" block right inside the real example below</strong>. It builds a query with format!</code>, quoting 'The Matrix'</code> by hand and pasting year</code> straight into the string.</p> Two problems, one fatal. The annoying one: I'm responsible for quoting and escaping every value, and I will</em> get it wrong the day a title contains an apostrophe. The fatal one: if that title ever comes from a user, they can close my string and append their own Cypher. '; MATCH (n) DETACH DELETE n //</code> and the graph is gone. This is injection, and "remember to escape everything, forever" is not a security strategy.</p> The way that ships now</h2> Parameters are bound</strong>, not interpolated. You hand the client real Rust values and it encodes them into proper Cypher literals for you. The example below shows both the commented-out "before" and the real "after":</p> /</span></span> * Copyright FalkorDB Ltd. 2023 - present</span></span> * Licensed under the MIT License.</span></span> /</span></span> </span> //</span>! Type-safe, injection-proof query parameters.</span></span> //</span>!</span></span> //</span>! Run with: `cargo run --example typed_params`</span></span> //</span>!</span></span> //</span>! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`).</span></span> </span> use</span> falkordb</span>::</span>{</span>FalkorClientBuilder</span>,</span> FalkorConnectionInfo</span>}</span>;</span></span> use</span> std</span>::</span>collections</span>::</span>BTreeMap</span>;</span></span> </span> fn</span> main</span>(</span>)</span> -></span> Result</span><</span>(</span>)</span>,</span> Box</span><</span>dyn</span> std</span>::</span>error</span>::</span>Error</span>></span>></span> {</span></span> let</span> connection_info</span>:</span> FalkorConnectionInfo</span> =</span> "</span>falkor://127.0.0.1:6379</span>"</span>.</span>try_into</span>(</span>)</span>?</span>;</span></span> let</span> client</span> =</span> FalkorClientBuilder</span>::</span>new</span>(</span>)</span></span> .</span>with_connection_info</span>(</span>connection_info</span>)</span></span> .</span>build</span>(</span>)</span>?</span>;</span></span> </span> let</span> mut</span> graph</span> =</span> client</span>.</span>select_graph</span>(</span>"</span>typed_params_example</span>"</span>)</span>;</span></span> </span> //</span> Start from a clean slate so the example is idempotent across runs.</span></span> let</span> _</span> =</span> graph</span>.</span>delete</span>(</span>)</span>;</span></span> </span> //</span> ── Before: hand-quoting and escaping every value yourself ──────────────</span></span> //</span> let mut params = HashMap::new();</span></span> //</span> params.insert("title".to_string(), "'The Matrix'".to_string()); // manual quotes!</span></span> //</span> params.insert("year".to_string(), 1999.to_string());</span></span> //</span> graph.query("CREATE (:Movie {title: $title, year: $year})").with_params(&params)...</span></span> </span> //</span> ── After: typed values, encoding handled for you ───────────────────────</span></span> graph</span></span> .</span>query</span>(</span>"</span>CREATE (:Movie </span>{</span>title: $title, year: $year, rating: $rating</span>}</span>)</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>title</span>"</span>,</span> "</span>The Matrix</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>year</span>"</span>,</span> 1999</span>)</span></span> .</span>with_param</span>(</span>"</span>rating</span>"</span>,</span> 8</span>.</span>7</span>)</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> </span> //</span> A string that would be a Cypher-injection attempt is stored as an inert literal.</span></span> graph</span></span> .</span>query</span>(</span>"</span>CREATE (:Movie </span>{</span>title: $title, year: $year</span>}</span>)</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>title</span>"</span>,</span> "</span>'; MATCH (n) DETACH DELETE n //</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>year</span>"</span>,</span> 2003</span>)</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> </span> //</span> Collections work too: `WHERE x IN $list`.</span></span> let</span> mut</span> titles</span> =</span> graph</span></span> .</span>query</span>(</span>"</span>MATCH (m:Movie) WHERE m.year IN $years RETURN m.title AS title ORDER BY m.year</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>years</span>"</span>,</span> [</span>1999</span>,</span> 2003</span>]</span>)</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> for</span> row</span> in</span> titles</span>.</span>data</span>.</span>by_ref</span>(</span>)</span> {</span></span> //</span> Read the column by its alias and convert it in one step.</span></span> let</span> title</span>:</span> String</span> =</span> row</span>?</span>.</span>try_get</span>(</span>"</span>title</span>"</span>)</span>?</span>;</span></span> println!</span>(</span>"</span>matched: </span>{</span>title</span>}</span>"</span>)</span>;</span></span> }</span></span> </span> //</span> Points can't be bound directly — pass the components as a map and wrap with `point()`.</span></span> let</span> coords</span> =</span> BTreeMap</span>::</span>from</span>(</span>[</span>(</span>"</span>latitude</span>"</span>,</span> 32</span>.</span>07</span>)</span>,</span> (</span>"</span>longitude</span>"</span>,</span> 34</span>.</span>79</span>)</span>]</span>)</span>;</span></span> let</span> mut</span> located</span> =</span> graph</span></span> .</span>query</span>(</span>"</span>RETURN point($p)</span>"</span>)</span></span> .</span>with_param</span>(</span>"</span>p</span>"</span>,</span> coords</span>)</span></span> .</span>execute</span>(</span>)</span>?</span>;</span></span> if</span> let</span> Some</span>(</span>row</span>)</span> =</span> located</span>.</span>data</span>.</span>next</span>(</span>)</span> {</span></span> println!</span>(</span>"</span>point: </span>{</span>:?</span>}</span>"</span>,</span> row</span>?</span>.</span>get_at</span>(</span>0</span>)</span>)</span>;</span></span> }</span></span> </span> graph</span>.</span>delete</span>(</span>)</span>?</span>;</span></span> Ok</span>(</span>(</span>)</span>)</span></span> }</span></span></code></pre>Source: examples/typed_params.rs</code></a> — compiled in CI.</p> A few things I want to point at, because they're the whole point:</p> with_param</code> takes typed Rust values.</strong> "The Matrix"</code> (a &str</code>), 1999</code> (an i64</code>), 8.7</code> (an f64</code>) — each is encoded as the correct Cypher literal. No quotes in your format string, because there is no format string.</li> Injection becomes a non-event.</strong> The line that binds "'; MATCH (n) DETACH DELETE n //"</code> as a title stores that whole thing as an inert string property. There is no parser context in which it can "break out," because it was never concatenated into the query text in the first place.</li> Collections just work.</strong> WHERE m.year IN $years</code> with [1999, 2003]</code> does what you'd hope — the array is bound as a Cypher list. Great for the IN</code>-list query you write fifteen times a week.</li> The type system catches the edges.</strong> Some values (a spatial point</code>) can't be bound as a raw literal, so the API makes you pass the components as a map and wrap them with point()</code>. That's the compiler steering you toward the one correct encoding instead of letting you guess.</li> </ul> The ergonomic version and the safe version are the same version. That's the bit I'm proud of: you don't choose</em> safety here, you just write the obvious code and safety falls out.</p> Why a graph client especially needs this</h2> Cypher is expressive, which is a polite way of saying there are a lot</em> of places to inject. Node labels, relationship types, property maps, list predicates, path patterns. Bound parameters keep your data</strong> out of the query structure</strong>, permanently. Your query text becomes a fixed template the server can even cache and re-plan efficiently, and your values ride alongside it where they can't do any harm.</p> It also makes the next</em> feature possible. Once values are typed on the way in, it's a short hop to making results typed on the way out — which is exactly where Part 3</a> goes: rows that don't lie about what they contain.</p> Why I keep betting on Rust for a graph database client Barak — Tue, 02 Jun 2026 00:00:00 +0000 Welcome to the dev log for the FalkorDB</a> Rust client</strong>. Over the next few posts I'm going to walk through a month of changes that took this crate from "it works" to "I'd actually hand this to a stranger." Type-safe parameters, header-aware rows, async streaming, an embedded server you can cargo run</code>, temporal values, retries, metrics, replica routing — the whole tour.</p> But first, the obvious question: why pour this much effort into a client library</em>, in Rust</em>, for a graph database? Let me make the case.</p> What FalkorDB is trying to be</h2> FalkorDB is a fast, low-latency graph database. Under the hood it represents the graph as sparse matrices and answers queries with linear algebra (GraphBLAS), which is a genuinely different bet from the pointer-chasing most graph databases do. The result is a database that stays quick when your graph gets big and your queries get hairy — exactly the workload that knowledge graphs and GenAI retrieval throw at you.</p> A database is only as good as the distance between your code</em> and its speed</em>. You can have the fastest engine on earth, and if the client makes you hand-concatenate query strings and pattern-match untyped blobs, people will write slow, buggy code on top of it. The client is</strong> the product, as far as most developers ever experience it. That's the part I work on, and that's why I care about it this much.</p> Why Rust</h2> I want a client that's fast</strong>, correct</strong>, and honest about failure</strong> — and Rust lets me have all three without picking two.</p> Correctness you can feel at compile time.</strong> Rust's type system is the best code reviewer I've ever had. A whole category of "oops" — SQL/Cypher injection, mismatched result columns, forgetting that the network can fail — can be turned from runtime surprises into compile errors. Most of this series is really just me handing more of my mistakes to the compiler.</li> Performance without a runtime tax.</strong> Zero-cost abstractions mean the ergonomic API and the fast API are the same API. A typed row doesn't cost you a heap allocation it didn't need.</li> One library, two worlds.</strong> The same crate ships a blocking</strong> client and a tokio</code> async</strong> client with the same ergonomics. (More on how, and what it costs, in Part 4</a>.)</li> It embeds anywhere.</strong> Rust drops into CLIs, servers, and other languages' runtimes without dragging a VM along. We even ship an embedded FalkorDB server</em> — see Part 5</a>.</li> </ul> Here's the whole thing in miniature — connect, query, iterate. This is the real examples/basic_usage.rs</code> from the repo:</p> /</span></span> * Copyright FalkorDB Ltd. 2023 - present</span></span> * Licensed under the MIT License.</span></span> /</span></span> </span> use</span> falkordb</span>::</span>{</span>FalkorClientBuilder</span>,</span> FalkorResult</span>}</span>;</span></span> </span> fn</span> main</span>(</span>)</span> -></span> FalkorResult</span><</span>(</span>)</span>></span> {</span></span> let</span> client</span> =</span> FalkorClientBuilder</span>::</span>new</span>(</span>)</span></span> .</span>with_connection_info</span>(</span>"</span>falkor://127.0.0.1:6379</span>"</span>.</span>try_into</span>(</span>)</span>?</span>)</span></span> .</span>build</span>(</span>)</span>?</span>;</span></span> </span> //</span> Dataset is available in the 'resources' directory</span></span> let</span> mut</span> graph</span> =</span> client</span>.</span>select_graph</span>(</span>"</span>imdb</span>"</span>)</span>;</span></span> </span> let</span> mut</span> cloned_graph</span> =</span> client</span>.</span>copy_graph</span>(</span>"</span>imdb</span>"</span>,</span> "</span>imdb_clone</span>"</span>)</span>?</span>;</span></span> </span> let</span> mut</span> res</span> =</span> graph</span>.</span>query</span>(</span>"</span>MATCH (a:actor) return a</span>"</span>)</span>.</span>execute</span>(</span>)</span>?</span>;</span></span> let</span> mut</span> clone_graph_res</span> =</span> cloned_graph</span>.</span>query</span>(</span>"</span>MATCH (a:actor) return a</span>"</span>)</span>.</span>execute</span>(</span>)</span>?</span>;</span></span> </span> //</span> Parses them one by one, to avoid unneeded performance hits</span></span> assert_eq!</span>(</span>res</span>.</span>data</span>.</span>len</span>(</span>)</span>,</span> 1317</span>)</span>;</span></span> assert_eq!</span>(</span>clone_graph_res</span>.</span>data</span>.</span>len</span>(</span>)</span>,</span> 1317</span>)</span>;</span></span> if</span> let</span> (</span>Some</span>(</span>orig</span>)</span>,</span> Some</span>(</span>cloned</span>)</span>)</span> =</span> (</span>res</span>.</span>data</span>.</span>next</span>(</span>)</span>,</span> clone_graph_res</span>.</span>data</span>.</span>next</span>(</span>)</span>)</span> {</span></span> println!</span>(</span>"</span>Original one: </span>{</span>orig:?</span>}</span>, Cloned one: </span>{</span>cloned:?</span>}</span>"</span>)</span>;</span></span> assert_eq!</span>(</span>orig</span>,</span> cloned</span>)</span>;</span></span> }</span></span> </span> //</span> We have already parsed one result</span></span> assert_eq!</span>(</span>res</span>.</span>data</span>.</span>len</span>(</span>)</span>,</span> 1316</span>)</span>;</span></span> assert_eq!</span>(</span>clone_graph_res</span>.</span>data</span>.</span>len</span>(</span>)</span>,</span> 1316</span>)</span>;</span></span> </span> //</span> more iterator usage:</span></span> for</span> (</span>orig</span>,</span> cloned</span>)</span> in</span> res</span>.</span>data</span>.</span>zip</span>(</span>clone_graph_res</span>.</span>data</span>)</span> {</span></span> println!</span>(</span>"</span>Original one: </span>{</span>orig:?</span>}</span>, Cloned one: </span>{</span>cloned:?</span>}</span>"</span>)</span>;</span></span> assert_eq!</span>(</span>orig</span>,</span> cloned</span>)</span>;</span></span> }</span></span> </span> cloned_graph</span>.</span>delete</span>(</span>)</span>?</span>;</span></span> </span> let</span> res_again</span> =</span> graph</span>.</span>query</span>(</span>"</span>MATCH (a:actor) return a</span>"</span>)</span>.</span>execute</span>(</span>)</span>?</span>;</span></span> let</span> as_vec</span> =</span> res_again</span>.</span>data</span>.</span>collect</span>::</span><</span>Vec</span><</span>_</span>></span>></span>(</span>)</span>;</span></span> assert_eq!</span>(</span>as_vec</span>.</span>len</span>(</span>)</span>,</span> 1317</span>)</span>;</span></span> </span> Ok</span>(</span>(</span>)</span>)</span></span> }</span></span></code></pre>Source: examples/basic_usage.rs</code></a> — compiled in CI.</p> Notice what you don't</em> see: no string-escaping, no unwrap()</code> confetti, no "parse this Vec<Vec<u8>></code> yourself." Reading a result is just iterating typed rows. We'll earn each of those niceties in later posts.</p> The promise of this blog: the code can't lie</h2> I have a personal grudge against tech blogs whose code doesn't compile. You copy a snippet from a post, paste it in, and discover the API moved on two releases ago and nobody told the prose.</p> So I built this blog to make that impossible. Every Rust sample you'll see is a real file in the repository</strong> — an examples/.rs</code> program or a benches/.rs</code> harness — that CI compiles on every push. At build time the site copies those exact files in and renders them. There is no hand-typed code on this blog. If a snippet is here, it built.</p> flowchart LR A["examples/.rs<br/>benches/*.rs"] -->\|"just build-examples (CI)"\| B["compiled, green check"] A -->\|"blog-sync: byte-for-byte copy"\| C["this blog post"] B -. guarantees .-> C </pre> The snippet you read is the file CI compiled.</figcaption> </figure> The same goes for numbers. When I show you a benchmark, it's a real criterion</code> harness, and the figures are a dated sample run you can reproduce with one command. No vibes-based performance claims.</p> It's a small obsession, but it's the one that makes the rest of this series trustworthy. Next time, the first place I taught the compiler to catch my mistakes: query parameters</strong>.</p> This is a developer dev log; opinions are mine and occasionally wrong in interesting ways. Corrections and heckling welcome on GitHub</a>.</p> </blockquote>

FalkorDB-rs Dev Log

Read your writes: opt-in replica routing via Sentinel

Barak — Wed, 24 Jun 2026 00:00:00 +0000

We made it to the finale. This one is short, but it's the post where a one-word default decision is actually a correctness decision in disguise — and getting it wrong is the kind of bug that doesn't show up until production, under load, intermittently. My favorite kind. (It is not my favorite kind.)

The setup</h2>
Behind Redis Sentinel, a FalkorDB deployment has a primary and one or more replicas. Reads can be served from replicas to spread load. The catch: a replica applies a write only after the primary has committed it. So a read from a replica can be slightly stale — it might not yet reflect a write you just made.

sequenceDiagram autonumber participant App participant C as falkordb client participant Sentinel participant P as primary participant Rep as replica C->>Sentinel: discover topology Sentinel-->>C: primary + replica addresses App->>C: query("CREATE ...") (write) C->>P: always routed to the primary App->>C: ro_query(...).prefer_replica() C->>Rep: read served from a replica (may be slightly stale) App->>C: ro_query(...).primary_only() C->>P: read-your-writes — forced onto the primary Note over C,Rep: PreferReplica falls back to the primary when no replica is available </pre>
Writes to the primary; reads where you ask — replica or primary.</figcaption> </figure>
The decision: stale-by-accident is not allowed</h2>
Here's the part I want to defend, because it was a breaking change and I made people opt back in.
The client used to route read-only queries to replicas automatically when they were available. That's great for throughput and quietly terrible for correctness: the classic failure is "create a thing, then immediately read it back, and it's not there" — because the read went to a replica that hadn't caught up. That's a heisenbug. It reproduces under load, on a good day, once.
So the default flipped: reads go to the primary unless you explicitly opt in. You don't get replication lag unless you ask for it. Throughput is a knob you turn on purpose, with your eyes open — not a default that silently trades correctness for a benchmark number. Routing is now controllable at two levels:

Per client — with_read_preference(ReadPreference::PreferReplica)</code> makes every read prefer a replica.</li>
Per query — ro_query(..).prefer_replica()</code> opts a single query in, and .primary_only()</code> forces a single query back onto the primary. That last one is the read-your-writes escape hatch: even on a replica-preferring client, the one read that has to be fresh can demand the primary.</li> </ul> Here's the real examples/readonly_replica.rs</code>: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Demonstrates opt-in routing of read-only queries to replica nodes. //! //! Routing reads to replicas is **opt-in**, because a FalkorDB replica applies writes only after //! the primary has committed them — a read served from a replica can be slightly **stale**. By //! default every read goes to the primary, so you never observe replication lag unless you ask for //! it. Opt in either: //! //! * **per client** — `FalkorClientBuilder::with_read_preference(ReadPreference::PreferReplica)` //! makes every read-only query prefer a replica, or //! * **per query** — `ro_query(..).prefer_replica()` opts a single query in (and //! `.primary_only()` forces a single query back onto the primary for read-your-writes paths). //! //! `PreferReplica` transparently falls back to the primary when no replica is available (for //! example a single-node deployment), so the same code runs everywhere. //! //! Set `FALKORDB_CONNECTION` to a Sentinel endpoint (for example //! `falkor://127.0.0.1:26379`) to see reads routed to replicas; otherwise it //! defaults to a local single node. use falkordb::{FalkorClientBuilder, FalkorResult, ReadPreference}; fn main() -> FalkorResult<()> { let connection_info = std::env::var("FALKORDB_CONNECTION") .unwrap_or_else(|_| "falkor://127.0.0.1:6379".to_string()); // Opt this client into replica reads by default. Drop `with_read_preference` (or pass // `ReadPreference::Primary`) to keep every read on the primary. let client = FalkorClientBuilder::new() .with_connection_info(connection_info.as_str().try_into()?) .with_read_preference(ReadPreference::PreferReplica) .build()?; // `replica_reads_available()` reports capability (a replica pool exists), while // `read_preference()` reports the client's default policy. if client.replica_reads_available() { println!("Replica connections are available; read-only queries may be served from them."); } else { println!("No readable replicas detected; read-only queries use the primary."); } println!("Default read preference: {:?}", client.read_preference()); let mut graph = client.select_graph("readonly_example"); // Writes always go to the primary. graph .query("CREATE (:Greeting {text: 'hello'})") .execute()?; // This read-only query follows the client default (PreferReplica) — served from a replica when // one is available, otherwise transparently from the primary. let mut greetings = graph .ro_query("MATCH (g:Greeting) RETURN g.text") .execute()?; for row in greetings.data.by_ref() { println!("replica-preferring read: {row:?}"); } // A read-your-writes path can force the primary for a single query, ignoring the client default. let mut fresh = graph .ro_query("MATCH (g:Greeting) RETURN g.text") .primary_only() .execute()?; for row in fresh.data.by_ref() { println!("primary (fresh) read: {row:?}"); } graph.delete()?; Ok(()) }</code></pre>Source: examples/readonly_replica.rs</code></a> — compiled in CI. The ergonomic details that make it safe to live with</h2> It degrades gracefully. PreferReplica</code> transparently falls back to the primary when no replica exists — a single-node dev box, say — so the same code runs in every environment. You don't write one path for laptops and another for production.</li> Capability and policy are separate questions. replica_reads_available()</code> tells you whether a replica pool even exists; read_preference()</code> tells you the client's default policy. Conflating "can I?" with "will I?" is how you get confusing behavior, so they're two honest accessors.</li> Asking for a replica on a write fails loudly. Request a replica for a writable query and you get a real error, not a quietly-wrong route to a node that can't serve it.</li> </ul> That's a wrap</h2> Eight posts, one theme: push correctness into the type system and the API defaults, so the easy path is the safe path. Typed parameters, honest rows, streaming async, an embedded server, temporal math, retries that can't double-write, privacy-safe telemetry, and now reads that don't accidentally read the past. That's a month. Every snippet you read across this series is a real file the CI compiled, and the benchmark in Part 4</a> is a real harness you can re-run. That wasn't an accident — it's the same principle as the code: make the trustworthy thing the default thing. Thanks for reading the dev log. The code's on GitHub</a>; come argue with me about any of it.

Production-grade: retries, tracing spans, metrics, and error hints Barak — Sun, 21 Jun 2026 00:00:00 +0000 A client library spends most of its life in production, where the network is hostile and the only thing you have at 3am is whatever the library decided to tell you. This batch of work was all about that life: surviving transient failures, explaining what's happening, and — when something does break — pointing at the fix. Retries that can't duplicate a write</h2> Retries are a loaded gun. Re-issue a read and worst case you did some redundant work; re-issue a write and you might have just charged a customer twice. So the retry policy here has one inviolable rule: writes are never retried. sequenceDiagram autonumber participant App participant C as falkordb client participant DB as FalkorDB App->>C: ro_query(...).execute() C->>DB: attempt 1 DB--xC: ConnectionDown (transient) Note over C: read-only + transient? eligible. backoff: 50ms, 100ms, 200ms ... capped at 1s C->>C: sleep(backoff), re-borrow a healed connection C->>DB: attempt 2 DB-->>C: result set C-->>App: Ok(rows) Note over App,DB: a write (query()) in the same spot is NEVER retried — it fails fast so it can't be applied twice </pre> Read-only + transient → retried with backoff. A write fails fast.</figcaption> </figure> It's off by default — without a policy, every operation runs exactly once, same as before. When you do opt in, only read-only / idempotent operations that fail with a transient connection error get retried, with bounded exponential backoff. Here's the real examples/retry.rs</code>: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Demonstrates the opt-in retry policy that re-issues eligible operations on transient //! connection failures. //! //! A [`RetryPolicy`] is **disabled by default**, so a client built without one attempts every //! operation exactly once (the previous behavior). When a policy is configured, read-only / //! idempotent operations that fail with a transient connection error are automatically retried //! with bounded backoff. **Writes are never retried**, so enabling a policy can never duplicate a //! write. //! //! Set `FALKORDB_CONNECTION` to point at another server (for example `falkor://127.0.0.1:6379`); //! it defaults to a local single node. use falkordb::{Backoff, FalkorClientBuilder, FalkorResult, RetryPolicy}; use std::time::Duration; fn main() -> FalkorResult<()> { let connection_info = std::env::var("FALKORDB_CONNECTION") .unwrap_or_else(|_| "falkor://127.0.0.1:6379".to_string()); // Retry read-only operations on transient connection failures: up to 4 attempts total // (1 initial try + 3 retries), with exponential backoff starting at 50ms and capped at 1s. let policy = RetryPolicy::read_only() .max_attempts(4) .backoff(Backoff::exponential(Duration::from_millis(50)).max_delay(Duration::from_secs(1))); let client = FalkorClientBuilder::new() .with_connection_info(connection_info.as_str().try_into()?) .with_retry_policy(policy) .build()?; let mut graph = client.select_graph("retry_example"); // Writes are NEVER auto-retried, even with a policy enabled, so a write can never be applied // twice. Classification is by the API you call: `query()` is always treated as a write. graph .query("CREATE (:Greeting {text: 'hello'})") .execute()?; // Read-only queries ARE eligible for retry. If the connection drops transiently here, the // client re-borrows a healed connection and re-issues the query (up to `max_attempts`), instead // of surfacing the error on the first blip. Use `ro_query()` (not `query()`) for retryable reads. let mut greetings = graph .ro_query("MATCH (g:Greeting) RETURN g.text") .execute()?; for row in greetings.data.by_ref() { println!("read-only result: {row:?}"); } graph.delete()?; Ok(()) }</code></pre>Source: examples/retry.rs</code></a> — compiled in CI. The classification is by the API you call, which is what makes it safe: query()</code> is always treated as a write and never retried; ro_query()</code> is eligible. There's no heuristic sniffing your Cypher to guess intent — you told the client what this is by which method you called, and it believes you. Enabling a policy can therefore never turn one write into two. That property mattered more to me than any amount of cleverness. Spans that tell you something, without leaking everything</h2> With the tracing</code> feature, every query- and procedure-execution span carries structured, low-cardinality fields you can actually slice on — the graph (db.namespace</code>), the command (db.operation.name</code>), whether it was read-only, the connection strategy, and the server-reported execution time and returned row count. The naming is OpenTelemetry-aligned on purpose, so this drops into your existing dashboards instead of inventing private conventions. /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Demonstrates the `tracing` span enrichment (run with `--features tracing`). //! //! With the `tracing` feature enabled, the query- and procedure-execution spans carry structured, //! low-cardinality fields you can slice on — the graph (`db.namespace`), the command //! (`db.operation.name`), whether it is read-only, the connection strategy, and a privacy-safe //! `db.query.fingerprint`. The raw query text and parameter values are never recorded by default. //! //! This installs a simple `tracing-subscriber` that prints each span (and its fields) as it closes, //! so you can see the enriched execution spans for the write and the read below. Run with: //! `cargo run --example observability --features tracing`. use falkordb::{FalkorClientBuilder, FalkorResult}; use tracing_subscriber::fmt::format::FmtSpan; fn main() -> FalkorResult<()> { // Print each span and its recorded fields when it closes. The execution spans are at TRACE // level, so enable TRACE to see them (a real app would scope this to the `falkordb` target). tracing_subscriber::fmt() .with_max_level(tracing::Level::TRACE) .with_span_events(FmtSpan::CLOSE) .with_target(true) .init(); let connection_info = std::env::var("FALKORDB_CONNECTION") .unwrap_or_else(|_| "falkor://127.0.0.1:6379".to_string()); // `with_query_logging(true)` would additionally record the raw Cypher as `db.query.text`; // it is off by default for privacy, so only the redacted fingerprint is recorded. let client = FalkorClientBuilder::new() .with_connection_info(connection_info.as_str().try_into()?) .build()?; let mut graph = client.select_graph("observability_example"); // A write: its span carries `db.operation.name = "GRAPH.QUERY"`, `db.falkordb.read_only = false`. graph .query("CREATE (:Movie {title: 'The Matrix', year: 1999})") .execute()?; // A read: its span carries `db.operation.name = "GRAPH.RO_QUERY"`, `read_only = true`, and a // `db.query.fingerprint` that is independent of the inlined `'The Matrix'` literal. let mut titles = graph .ro_query("MATCH (m:Movie) WHERE m.title = 'The Matrix' RETURN m.year") .execute()?; for row in titles.data.by_ref() { println!("read-only result: {row:?}"); } graph.delete()?; Ok(()) }</code></pre>Source: examples/observability.rs</code></a> — compiled in CI. Here's the design decision I'll defend hardest: the raw query text and parameter values are not recorded by default. Instead the span carries a db.query.fingerprint</code> — a redacted identity for the query shape that's independent of the inlined literals. So WHERE m.title = 'The Matrix'</code> and WHERE m.title = 'Heat'</code> share a fingerprint, and you can aggregate "this query shape is slow" without spraying user data — or secrets — across your tracing backend. You can opt into full query logging with with_query_logging(true)</code> when you're debugging locally, but you have to ask. Observability should never be the reason you failed an audit. Metrics and actionable errors</h2> Two more pieces round it out: A metrics</code> feature emits bounded counters and histograms — executions, retries, in-flight requests, pool-wait time. "Bounded" is the key word: the cardinality is fixed, so your metrics bill doesn't explode because someone parameterized a label with a user ID. Plays directly into the metrics</code> ecosystem.</li> FalkorDBError::mitigation_hint()</code> — because an error that only tells you what went wrong is half an error. The hint tells you what to do about it. It's the difference between ConnectionDown</code> and "ConnectionDown</code> — the server may be restarting or unreachable; check connectivity and consider a retry policy." Future-me, staring at a log line, is the customer for that sentence.</li> </ul> None of this is glamorous. All of it is the difference between a library you use and a library you trust. The finale, Part 8</a>, is about trust of a subtler kind: reading from replicas without accidentally reading the past. Typed mapping with serde, and temporal values that do real math Barak — Thu, 18 Jun 2026 00:00:00 +0000 Part 3</a> gave us honest rows you read column-by-column. This post is about two ways to stop reading column-by-column: map a whole row into your own type with serde</code>, and get temporal values back as real types instead of opaque scalars. Rows into structs, with serde</code></h2> Per-column try_get</code> is great until you're pulling ten fields off a node, at which point it's ten lines of boilerplate that all say the same thing. With the serde</code> feature you derive Deserialize</code> on your struct and let the row map itself: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Typed result mapping with `serde`. //! //! Run with: `cargo run --example typed_mapping --features serde` //! //! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`). use falkordb::{FalkorClientBuilder, FalkorConnectionInfo}; use serde::Deserialize; #[derive(Debug, Deserialize)] struct Movie { title: String, year: i64, #[serde(default)] rating: Option<f64>, } fn main() -> Result<(), Box<dyn std::error::Error>> { let connection_info: FalkorConnectionInfo = "falkor://127.0.0.1:6379".try_into()?; let client = FalkorClientBuilder::new() .with_connection_info(connection_info) .build()?; let mut graph = client.select_graph("typed_mapping_example"); // Start from a clean slate so the example is idempotent across repeated runs. // The graph may not exist yet, so ignore a "missing graph" error here. let _ = graph.delete(); graph .query("CREATE (:Movie {title: 'Heat', year: 1995, rating: 8.3})") .execute()?; // ── Value-level mapping ────────────────────────────────────────────────── // Without typed mapping you would hand-match every `FalkorValue` variant. // With the `serde` feature, deserialize a single returned value into a struct: let mut result = graph.query("MATCH (m:Movie) RETURN m").execute()?; for row in result.data.by_ref() { if let Some(node) = row?.into_iter().next() { let movie: Movie = node.deserialize_into()?; println!( "value: {} ({}) rating={:?}", movie.title, movie.year, movie.rating ); } } // ── Row-level mapping with `query_as` ──────────────────────────────────── // Map every row in one shot. A single-column `RETURN m` maps the node's properties: let movies: Vec<Movie> = graph .query("MATCH (m:Movie) RETURN m") .query_as::<Movie>() .execute()? .data .collect::<Result<_, _>>()?; for movie in &movies { println!("row: {} ({})", movie.title, movie.year); } // Multi-column rows map column aliases onto struct fields: let summaries: Vec<Movie> = graph .query("MATCH (m:Movie) RETURN m.title AS title, m.year AS year") .query_as::<Movie>() .execute()? .data .collect::<Result<_, _>>()?; for movie in &summaries { println!("aliased: {} ({})", movie.title, movie.year); } // Scalars work too — `RETURN count(m)` is a single-column row: let counts: Vec<i64> = graph .query("MATCH (m:Movie) RETURN count(m)") .query_as::<i64>() .execute()? .data .collect::<Result<_, _>>()?; println!("count: {counts:?}"); graph.delete()?; Ok(()) }</code></pre>Source: examples/typed_mapping.rs</code></a> — compiled in CI. What I like here is that it works at three levels without three different APIs: Value-level: node.deserialize_into::<Movie>()</code> turns a single returned node into a struct.</li> Row-level with query_as</code>: RETURN m</code> maps the node's properties onto your fields; a multi-column RETURN m.title AS title, m.year AS year</code> maps the aliases onto the same fields. Your RETURN</code> and your struct meet in the middle, by name.</li> Scalars: RETURN count(m)</code> deserializes straight into i64</code>. Even the degenerate case is consistent.</li> </ul> And because it's serde</code>, the usual tools just work — #[serde(default)]</code> on rating: Option<f64></code> means a missing property is None</code> instead of an error. You already know this vocabulary; the client just speaks it. Temporal values that aren't lying integers</h2> Now the one that's secretly hard. FalkorDB has real temporal types — date</code>, time</code>/localtime</code>, duration</code>, datetime</code>. For a while the client surfaced some of these as Unparseable</code>, which is a polite way of saying "here's a blob, you figure it out." That's a trap: the moment you turn a date into a bare i64</code> to do arithmetic, you've thrown away the type system's ability to stop you from adding a duration to a count of bananas. So we decode them into proper Date</code> / Time</code> / Duration</code> / DateTime</code> value types, each exposing its scalar as a typed Seconds</code> — not a raw integer — and DateTime</code>/Duration</code> get a small, type-safe algebra: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Decoding FalkorDB temporal values and using the type-safe temporal algebra. //! //! Run with: `cargo run --example temporal` (needs a FalkorDB server on 127.0.0.1:6379). use falkordb::{Date, DateTime, Duration, FalkorClientBuilder, FalkorResult, Time}; fn main() -> FalkorResult<()> { let client = FalkorClientBuilder::new() .with_connection_info("falkor://127.0.0.1:6379".try_into()?) .build()?; let mut graph = client.select_graph("temporal_example"); let _ = graph.delete(); // FalkorDB returns `date` / `time` / `duration` as typed, seconds-based scalars. The client // decodes them into the `Date` / `Time` / `Duration` value types rather than leaving them // `Unparseable`, so you can read them with strict typed access. let mut result = graph .query("RETURN date('1947-11-29') AS d, localtime() AS t, duration({days: 3}) AS dur") .execute()?; let row = result.data.next().expect("expected a row")?; let d: Date = row.try_get("d")?; let t: Time = row.try_get("t")?; let dur: Duration = row.try_get("dur")?; // Each value exposes its scalar as a typed `Seconds` (not a bare `i64`) — call `.get()` for the // underlying integer. This keeps a temporal scalar from being silently mixed with a plain int. println!("date is {} seconds since the Unix epoch", d.seconds().get()); println!("localtime is {} seconds", t.seconds()); println!("duration is {} seconds", dur.seconds().get()); println!( "duration as std::time::Duration: {:?}", dur.as_std_duration() ); // `DateTime` and `Duration` support a small, type-safe algebra. Subtracting two instants yields // a `Duration`; shifting an instant by a `Duration` yields another `DateTime`. let instant = DateTime::new(d.seconds().get()); let earlier = DateTime::new(d.seconds().get() - 60); let elapsed: Duration = instant - earlier; assert_eq!(elapsed.seconds().get(), 60); println!("instant is {} seconds after `earlier`", elapsed.seconds()); // Shifting forward by a duration and back again is a no-op. assert_eq!(instant + dur - dur, instant); // Overflow-checked variants return `None` instead of panicking. assert!(DateTime::new(i64::MAX).checked_add(dur).is_none()); // Nonsensical combinations simply have no impl and fail to compile, e.g.: // let _ = instant + earlier; // error: cannot add two instants graph.delete()?; Ok(()) }</code></pre>Source: examples/temporal.rs</code></a> — compiled in CI. The algebra is the point, and it's deliberately restrictive: DateTime − DateTime → Duration</code>. The difference between two instants is a span. ✓</li> DateTime ± Duration → DateTime</code>. Shifting an instant by a span gives another instant. ✓</li> DateTime + DateTime</code>? That has no meaning, so it has no impl and won't compile. You can't add two Tuesdays together, and now the compiler agrees with you.</li> </ul> There are checked_*</code> variants that return None</code> instead of panicking on overflow, because temporal arithmetic at the extremes is exactly where the silent wraparound bugs hide. DateTime::new(i64::MAX) .checked_add(dur)</code> is None</code>, not a wrapped-around timestamp from the Bronze Age. This is a tiny domain, but it's a perfect showcase for the whole thesis of this series: encode the rules of your domain into types, and a category of bugs simply stops being expressible. Next, we take that same "make failure honest" energy to the network itself — retries, tracing, and metrics</a>. Batteries included: an embedded FalkorDB you can cargo run Barak — Mon, 15 Jun 2026 00:00:00 +0000 Every "getting started" guide has the same speed bump on line one: first, run a server. It's a small ask, but it's friction at the exact moment someone is deciding whether your library is worth their afternoon. So we removed it. With the embedded</code> feature, the client can start a real FalkorDB for you, in-process, and shut it down when you're done. What "embedded" actually does</h2> The embedded server spins up redis-server</code> as a child process with the FalkorDB module loaded, waits until it answers PING</code>, hands you a connected client, and tears the whole thing down on drop. The interesting part is where the module comes from. sequenceDiagram autonumber participant App participant E as EmbeddedServer participant Cache as module cache / build-time bundle participant R as redis-server (child process) participant DB as FalkorDB module App->>E: build() with FalkorConnectionInfo::Embedded E->>R: check `redis-server --version` (must be >= 8.0) E->>Cache: resolve falkordb.so (cached / downloaded / embedded bytes) Cache-->>E: module path E->>R: spawn redis-server --loadmodule falkordb.so E->>R: poll PING until ready R-->>E: PONG E-->>App: connected client Note over App,DB: on drop, the child server is shut down for you </pre> Resolve the module, spawn the server, wait for ready, hand back a client.</figcaption> </figure> There are three ways the falkordb.so</code> module gets resolved, in increasing order of "I have no network and I like it that way": Auto-download (default). If the module isn't already present, it's fetched from the official releases, verified against a pinned SHA-256 checksum, and cached locally. First run pays the download; every run after is instant. The redis-server</code> binary itself is not downloaded — it's found on your PATH</code> — so this leans on a tool you already have rather than smuggling in a binary.</li> Already-installed / offline. Point at an existing module, or disable downloading and let it search common system locations. No network at all.</li> Build-time bundle. Enable the embedded-bundle</code> feature instead, and a build.rs</code> fetches the module for your build target at compile time and bakes it into your binary with include_bytes!</code>. The running process then needs zero network — it extracts the embedded bytes and goes. This is the one for air-gapped and network-isolated deployments, and it's why the feature exists.</li> </ol> Here's the real examples/embedded_usage.rs</code> — note that the usage is identical regardless of how the module is sourced; only the EmbeddedConfig</code> differs: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Example demonstrating the embedded FalkorDB server feature. //! //! This example shows how to use FalkorDB with an embedded Redis server //! that has the FalkorDB module loaded. This is useful for: //! - Testing without external dependencies //! - Embedded applications //! - Quick prototyping //! //! # Self-Contained Mode //! //! The embedded server can auto-provision the FalkorDB **module** via the //! `auto_download` option (enabled by default). When enabled, a missing //! `falkordb.so` is downloaded from the official FalkorDB releases, verified //! against a pinned SHA-256 checksum and cached locally, so the embedded server //! "just works" without a pre-installed module. //! //! The `redis-server` binary is **not** downloaded — it is located on the host //! via `PATH` or `redis_server_path`. Install it from your package manager //! (e.g. `brew install redis`, `apt-get install redis-server`). //! //! # Using an already-installed FalkorDB //! //! To run fully offline against binaries already on the machine, either set //! `falkordb_module_path` explicitly or disable `auto_download` (common system //! locations are still searched). See `already_installed_config()` below. //! //! # Build-time bundle (offline at runtime) //! //! For network-isolated deployments, enable the `embedded-bundle` feature instead //! of `embedded`. A `build.rs` fetches the module for the build target at compile //! time and embeds it in the binary, so the running process needs **no network**. //! The same `EmbeddedConfig` / API shown here works unchanged; only the module //! source differs. Run it with: //! ```bash //! cargo run --example embedded_usage --features embedded-bundle //! ``` //! //! # Platform-Specific Requirements //! //! ## macOS //! The FalkorDB module requires OpenMP (libomp) on macOS. If not already installed via //! Homebrew, install it with: `brew install libomp` //! //! # License Note //! //! The FalkorDB module binary (downloaded at runtime, or embedded at build time //! with `embedded-bundle`) is licensed under the Server Side Public License //! (SSPL) v1. See https://www.falkordb.com/ for licensing details. //! //! # Running this example //! ```bash //! cargo run --example embedded_usage --features embedded //! ``` use falkordb::{EmbeddedConfig, FalkorClientBuilder, FalkorConnectionInfo, FalkorResult}; /// Build a config that uses binaries already installed on the machine, without /// any network access: redis-server is taken from `PATH` and the FalkorDB /// module from the given path (or common system locations when left as `None`). #[allow(dead_code)] fn already_installed_config() -> EmbeddedConfig { EmbeddedConfig { // Disable downloading: resolve only explicit/system binaries. auto_download: false, // Optionally pin an installed module; `None` searches system locations. falkordb_module_path: None, ..Default::default() } } fn main() -> FalkorResult<()> { println!("Starting embedded FalkorDB example..."); // Default config: download + cache the FalkorDB module if missing, and find // redis-server on PATH. Swap in `already_installed_config()` to run offline // against an existing install instead. let embedded_config = EmbeddedConfig::default(); // You can also customize the configuration: // let embedded_config = EmbeddedConfig { // redis_server_path: Some(PathBuf::from("/path/to/redis-server")), // falkordb_module_path: Some(PathBuf::from("/path/to/falkordb.so")), // db_dir: Some(PathBuf::from("/tmp/my_falkordb")), // db_filename: "mydb.rdb".to_string(), // socket_path: Some(PathBuf::from("/tmp/falkordb.sock")), // start_timeout: Duration::from_secs(10), // auto_download: true, // falkordb_version: None, // or Some("v4.18.10".to_string()) // cache_dir: None, // or Some(PathBuf::from("/tmp/fk-cache")) // }; println!("Creating client with embedded FalkorDB server..."); // Build a client with embedded FalkorDB let client = FalkorClientBuilder::new() .with_connection_info(FalkorConnectionInfo::Embedded(embedded_config)) .build()?; println!("Connected to embedded FalkorDB server!"); // Now use the client normally let mut graph = client.select_graph("social"); // Create some nodes println!("Creating nodes..."); graph .query("CREATE (:Person {name: 'Alice', age: 30})") .execute()?; graph .query("CREATE (:Person {name: 'Bob', age: 25})") .execute()?; graph .query("CREATE (:Person {name: 'Charlie', age: 35})") .execute()?; // Create relationships println!("Creating relationships..."); graph .query( "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:KNOWS]->(b)", ) .execute()?; graph .query( "MATCH (b:Person {name: 'Bob'}), (c:Person {name: 'Charlie'}) CREATE (b)-[:KNOWS]->(c)", ) .execute()?; // Query the graph println!("\nQuerying the graph:"); let result = graph .query("MATCH (p:Person) RETURN p.name, p.age ORDER BY p.age") .execute()?; println!("Found {} results:", result.data.len()); for row in result.data { println!(" {:?}", row); } // Query with relationships println!("\nQuerying relationships:"); let result = graph .query("MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name") .execute()?; println!("Found {} relationships:", result.data.len()); for row in result.data { println!(" {:?}", row); } // Clean up println!("\nDeleting graph..."); graph.delete()?; println!("Example completed successfully!"); println!("The embedded server will be automatically shut down when the client is dropped."); Ok(()) }</code></pre>Source: examples/embedded_usage.rs</code></a> — compiled in CI. The detail I'm quietly proud of</h2> Two, actually. First, the embedded server now pre-flights redis-server --version</code> and fails early, with a clear message, if it's older than the 8.0 the module requires. The failure mode it replaces — a server that starts and then mysteriously can't load the module — is exactly the kind of thing that eats an hour of someone's day. Fail fast, fail legible. Second, the build-time bundle is genuinely hermetic. The checksum verification on the download path isn't decoration: a graph module is native code you're loading into your process, and "download some bytes and run them" without verifying them is how you end up in an incident review. Pinned version, pinned checksum, or embedded-at-build-time bytes. Pick your paranoia level. Why this matters more for a graph database</h2> Graph code is fiddly to test. You want a real engine — Cypher semantics, real planning, real results — not a mock that lies to you. Embedded mode means your integration tests boot an actual FalkorDB per run with no external setup, and your CI doesn't need a service container just to check that a MATCH</code> returns what you think. It collapses the distance between "I have an idea" and "I ran it against the real thing" to a single cargo run</code>. That distance is where adoption lives or dies. Next: the values inside those nodes. Part 6</a> is about mapping rows straight into your structs with serde</code>, and decoding temporal values into types with actual arithmetic. Async all the way down: streaming results and connection multiplexing Barak — Fri, 12 Jun 2026 00:00:00 +0000 This is the post I'd been looking forward to writing, because it's where the Rust bet from Part 1</a> really pays rent. Two things landed: result sets became async streams, and the async client learned to multiplex many concurrent queries over a few shared sockets. Then I benchmarked it, because claims without numbers are just vibes. Results are streams</h2> On the async client, a result set's data</code> is a Stream<Item = FalkorResult<Row>></code>. Same fallible, header-aware row from Part 3</a> — now it arrives lazily and composes with the entire futures</code> toolbox. sequenceDiagram autonumber participant App participant S as Row stream participant DB as FalkorDB App->>DB: GRAPH.RO_QUERY DB-->>S: header + result set loop for each row, lazily App->>S: .next().await S-->>App: Ok(Row) — or Err you can `?` end Note over App,S: compose with the futures toolbox: map / try_collect / buffer_unordered(8) </pre> Rows arrive lazily; errors stay first-class.</figcaption> </figure> Here's the real examples/async_stream.rs</code>: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ #![recursion_limit = "256"] //! Async streaming results with `futures::StreamExt` / `TryStreamExt`. //! //! Run with: `cargo run --example async_stream --features tokio` //! //! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`). use falkordb::{FalkorClientBuilder, FalkorResult}; use futures::{StreamExt, TryStreamExt}; #[tokio::main(flavor = "multi_thread")] async fn main() -> FalkorResult<()> { let client = FalkorClientBuilder::new_async() .with_connection_info("falkor://127.0.0.1:6379".try_into()?) .build() .await?; let mut graph = client.select_graph("async_stream_example"); let _ = graph.delete().await; graph .query("UNWIND range(1, 5) AS i CREATE (:Movie {year: 1990 + i})") .execute() .await?; // ── 1. Collect a whole typed stream in one line ───────────────────────── // `data` is a `Stream`; map each row to a typed value and `try_collect`. let years: Vec<i64> = graph .query("MATCH (m:Movie) RETURN m.year AS year ORDER BY year") .execute() .await? .data .map(|row| row?.try_get::<i64>("year")) .try_collect() .await?; println!("years: {years:?}"); // ── 2. Fan out a follow-up query per row, with bounded concurrency ────── // The graph handle is `Send + Clone` (it shares one schema cache), so each unit of work just // clones it. `buffer_unordered` keeps at most 8 follow-up queries in flight at once. let mut next_years: Vec<i64> = graph .query("MATCH (m:Movie) RETURN m.year AS year") .execute() .await? .data .map(|row| { let mut g = graph.clone(); async move { let year: i64 = row?.try_get("year")?; let mut r = g .query(format!("RETURN {year} + 1 AS next")) .execute() .await?; r.data .try_next() .await? .expect("a row") .try_get::<i64>("next") } }) .buffer_unordered(8) .try_collect() .await?; next_years.sort_unstable(); println!("next years: {next_years:?}"); graph.delete().await?; Ok(()) }</code></pre>Source: examples/async_stream.rs</code></a> — compiled in CI. The bit that makes me happy is the second half: a stream of rows, each fanning out into a follow-up query, with buffer_unordered(8)</code> keeping at most eight in flight. That's backpressure-aware concurrency in about five lines, and it falls out of treating results as a Stream</code> instead of inventing a bespoke cursor API. Reuse beats reinvention. Many queries, few sockets: multiplexing</h2> The other half is how those concurrent queries hit the wire. The async client supports two connection strategies: Pooled — a fixed set of connections; each query borrows one exclusively for its duration.</li> Multiplexed — a few auto-reconnecting sockets, each carrying several in-flight commands at once. Queries are pipelined and their replies correlated back to the right caller.</li> </ul> sequenceDiagram autonumber participant T1 as task #1 participant T2 as task #2 participant T3 as task #64 participant M as multiplexer (4 sockets) participant DB as FalkorDB T1->>M: ro_query("RETURN 1") T2->>M: ro_query("RETURN 1") T3->>M: ro_query("RETURN 1") Note over M,DB: requests are pipelined over the shared sockets, not blocked on an exclusive connection each M->>DB: GRAPH.RO_QUERY (pipelined) DB-->>M: replies, correlated back to each task M-->>T1: typed Row M-->>T2: typed Row M-->>T3: typed Row </pre> Multiplexing: 64 tasks, 4 sockets, replies correlated back.</figcaption> </figure> examples/multiplexed_async.rs</code> fires 64 independent queries across 4 shared sockets: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ #![recursion_limit = "256"] //! Demonstrates the multiplexed async connection strategy: many concurrent queries //! share a small number of auto-reconnecting sockets, each carrying several in-flight //! commands at once. //! //! Run a FalkorDB instance first (e.g. `docker run -p 6379:6379 falkordb/falkordb`), then //! `cargo run --example multiplexed_async --features tokio`. use falkordb::{ConnectionStrategy, FalkorClientBuilder, FalkorResult}; use futures::StreamExt; use std::num::NonZeroU8; use std::sync::Arc; use tokio::task::JoinSet; // Usage of the asynchronous client REQUIRES the multi-threaded rt #[tokio::main(flavor = "multi_thread")] async fn main() -> FalkorResult<()> { // Explicitly select the multiplexed strategy with 4 shared sockets. This is also the // default for `new_async()` (with 8 sockets), so `with_connection_strategy` here is // purely to make the choice visible. let client = Arc::new( FalkorClientBuilder::new_async() .with_connection_info("falkor://127.0.0.1:6379".try_into()?) .with_connection_strategy(ConnectionStrategy::Multiplexed { connections: NonZeroU8::new(4).unwrap(), }) .build() .await?, ); println!( "effective strategy: {:?} ({} connections)", client.connection_strategy(), client.connection_pool_size() ); // Fire many independent queries concurrently. With multiplexing, these are pipelined // over the shared sockets rather than each waiting for an exclusive connection. let mut join_set = JoinSet::new(); for i in 0..64 { let client = client.clone(); join_set.spawn(async move { let mut graph = client.select_graph("multiplexed_demo"); let mut res = graph.ro_query("RETURN 1").execute().await?; let value = res .data .next() .await .and_then(|row| row.ok().and_then(|r| r.try_get_at::<i64>(0).ok())); FalkorResult::Ok((i, value)) }); } let mut completed = 0; while let Some(joined) = join_set.join_next().await { let (_i, _value) = joined.expect("task should not panic")?; completed += 1; } println!("completed {completed} concurrent queries over 4 multiplexed sockets"); client.select_graph("multiplexed_demo").delete().await.ok(); Ok(()) }</code></pre>Source: examples/multiplexed_async.rs</code></a> — compiled in CI. Now, the numbers</h2> Here's where I have to be honest instead of triumphant. Multiplexing is not free, and it is not always faster — it's faster under contention. The benchmark is the real benches/async_strategies.rs</code> harness; it runs the same batch of concurrent RETURN 1</code> reads against both strategies at a fixed 8 connections, across rising concurrency. (RETURN 1</code> is deliberate: it isolates the client's connection behavior from query-planning cost.) Async read throughput at 8 connections — pooled vs multiplexed</div> Concurrent reads</th> Pooled (mean)</th> Multiplexed (mean)</th> Speedup</th></tr></thead> 1</td> 315.3 µs</td> 384.3 µs</td> 0.82×</td></tr> 8</td> 815.0 µs</td> 862.7 µs</td> 0.94×</td></tr> 64</td> 5.58 ms</td> 3.69 ms</td> 1.51×</td></tr> 256</td> 20.43 ms</td> 11.85 ms</td> 1.72×</td></tr> </tbody> </table> Measured 2026-06-24 · Darwin arm64, Apple M1 Pro · FalkorDB falkordb/falkordb@sha256:e4b43a2c5231e3c96b8dccec3d6b0f212e057435f4dc0fd63d73b642a20f958d</code> · criterion 0.8 · commit d47fc61</code>. Reproduce with just bench</code>. </figcaption> </figure> Read that table honestly: At concurrency 1, pooling wins. One query at a time has nothing to multiplex, and the multiplexer's bookkeeping is pure overhead. The speedup is below 1.0 — multiplexing is slightly slower here, and pretending otherwise would be lying to you.</li> As concurrency climbs, multiplexing pulls ahead. By 64 concurrent reads it's ~1.5× faster, and by 256 it's ~1.7×, because the pooled strategy is serializing waves of queries through 8 exclusive connections while the multiplexer keeps many commands in flight per socket.</li> </ul> So the guidance writes itself: a request/response app doing one query at a time? Pooled is simple and great. A server fanning out hundreds of concurrent graph reads? Multiplex. The default for the async client is multiplexed with 8 sockets, which is the right call for the server workloads people actually point this at. The harness, by the way, skips itself cleanly when no server is reachable, so it stays runnable in CI without flaking — a small thing I care about a lot, and the subject of more than one bug fix. You can reproduce the table with just bench</code> against your own server; your numbers will differ, which is exactly why they're labeled with the machine and date. Next up, the feature that means you don't even need a server running to try any of this: the embedded FalkorDB</a>. Rows that don't lie: header-aware, fallible result iteration Barak — Tue, 09 Jun 2026 00:00:00 +0000 In Part 2</a> we made the data going in honest. This post is about the data coming out. The old result API had two original sins, and if you've used a database driver in a dynamically-typed mood you'll recognize both: you addressed columns by position (row[0]</code>, row[1]</code> — good luck when someone reorders the RETURN</code>), and a value that didn't match your expectation tended to surface as a panic somewhere deep in iteration. Both of those are the kind of bug that passes code review and then pages you at 2am. The new shape</h2> Two changes, and they compose: Result sets are header-aware. A row knows its column names, so you read by alias — row.try_get("year")</code> — not by a magic index.</li> Iteration is fallible. The result stream yields FalkorResult<Row></code>. A row that fails to parse is a real Err</code> you can ?</code>, not a landmine.</li> </ol> Here's the real examples/rows.rs</code>: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Header-aware result rows: reading columns by name or index, with strict typed access. //! //! Run with: `cargo run --example rows` //! //! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`). use falkordb::{FalkorClientBuilder, FalkorConnectionInfo, FalkorValue}; fn main() -> Result<(), Box<dyn std::error::Error>> { let connection_info: FalkorConnectionInfo = "falkor://127.0.0.1:6379".try_into()?; let client = FalkorClientBuilder::new() .with_connection_info(connection_info) .build()?; let mut graph = client.select_graph("rows_example"); // Start from a clean slate so the example is idempotent across runs. let _ = graph.delete(); graph .query( "CREATE (:Movie {title: 'The Matrix', year: 1999, rating: 8.7}), (:Movie {title: 'Heat', year: 1995, rating: 8.3})", ) .execute()?; // ── Read columns by alias, converted to the type you ask for ──────────── let mut result = graph .query( "MATCH (m:Movie) RETURN m.title AS title, m.year AS year, m.rating AS rating ORDER BY m.year", ) .execute()?; // `data` yields `FalkorResult<Row>`, so a row that fails to parse is a real `Err` you can `?`. for row in result.data.by_ref() { let row = row?; let title: String = row.try_get("title")?; let year: i64 = row.try_get("year")?; let rating: f64 = row.try_get("rating")?; println!("{title} ({year}) — rated {rating}"); } // ── Read by index, and borrow the raw value without converting ────────── let mut counted = graph.query("MATCH (m:Movie) RETURN count(m)").execute()?; if let Some(row) = counted.data.next() { let row = row?; let count: i64 = row.try_get_at(0)?; println!("movies: {count}"); // `get_at` borrows the underlying `FalkorValue` without converting or cloning. assert_eq!(row.get_at(0), Some(&FalkorValue::I64(count))); } // ── Collect a whole result set; `collect` short-circuits on the first error ── let titles: Vec<String> = graph .query("MATCH (m:Movie) RETURN m.title AS title ORDER BY m.title") .execute()? .data .map(|row| row?.try_get::<String>("title")) .collect::<Result<_, _>>()?; println!("titles: {titles:?}"); // ── Turn a row into a column -> value map ─────────────────────────────── let mut as_map = graph .query("MATCH (m:Movie) RETURN m.title AS title, m.year AS year ORDER BY m.year LIMIT 1") .execute()?; if let Some(row) = as_map.data.next() { let map = row?.into_map(); println!("oldest movie as a map: {map:?}"); } graph.delete()?; Ok(()) }</code></pre>Source: examples/rows.rs</code></a> — compiled in CI. Why FalkorResult<Row></code> is the important part</h2> Look at the iterator item type. It's not Row</code>, it's FalkorResult<Row></code>. That one decision ripples outward in the nicest way: ?</code> works mid-iteration. let row = row?;</code> and the unhappy path is handled the same way you handle every other error in Rust. No special "did this row secretly fail?" dance.</li> collect</code> short-circuits. Collecting into a Result<Vec<_>, _></code> stops at the first bad row and hands you the error. One malformed value doesn't get silently dropped or turned into a default.</li> Typed access is explicit. try_get::<i64>("year")</code> says exactly what you expect, and converts in one step. If the column is actually a string, you get an Err</code> describing the mismatch — at the call site, where you can do something about it.</li> </ul> And when you don't want to convert, get_at</code> borrows the raw FalkorValue</code> without cloning, so the escape hatch is there when you need to inspect the wire value directly. Ergonomics shouldn't cost you control. The "by name" thing is not a small thing</h2> I want to dwell on reading columns by alias for a second, because it's the feature that quietly prevents the most bugs. Positional access couples your Rust code to the order of your RETURN</code> clause. The day someone adds a column, or reorders two for readability, every positional index downstream is now silently pointing at the wrong data — and nothing fails, it just returns nonsense. Reading row.try_get("year")</code> is immune to that. The query can grow and shuffle; your code keeps asking for year</code> and keeps getting year</code>. There's also a tidy into_map()</code> when you genuinely want the whole row as a column → value</code> map — handy for logging or for shoving a row into something generic. This is about as far as the untyped row API goes. The natural next question is "can I skip the per-column try_get</code> and just deserialize a row into my own struct?" Yes — that's the serde</code> story in Part 6</a>. But first, the feature I had the most fun building: making the whole thing async and streaming. Stop hand-quoting Cypher: type-safe, injection-proof parameters Barak — Sat, 06 Jun 2026 00:00:00 +0000 Every database client eventually has the same coming-of-age moment: the day it stops letting you build queries with string concatenation. Today's the day for this one. The bad old way</h2> Here's the shape of code I never want to write again — and rather than hand-type it (this blog has a rule: no uncompiled Rust), I'll point you at the commented-out "before" block right inside the real example below. It builds a query with format!</code>, quoting 'The Matrix'</code> by hand and pasting year</code> straight into the string. Two problems, one fatal. The annoying one: I'm responsible for quoting and escaping every value, and I will get it wrong the day a title contains an apostrophe. The fatal one: if that title ever comes from a user, they can close my string and append their own Cypher. '; MATCH (n) DETACH DELETE n //</code> and the graph is gone. This is injection, and "remember to escape everything, forever" is not a security strategy. The way that ships now</h2> Parameters are bound, not interpolated. You hand the client real Rust values and it encodes them into proper Cypher literals for you. The example below shows both the commented-out "before" and the real "after": /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ //! Type-safe, injection-proof query parameters. //! //! Run with: `cargo run --example typed_params` //! //! Requires a running FalkorDB instance (defaults to `127.0.0.1:6379`). use falkordb::{FalkorClientBuilder, FalkorConnectionInfo}; use std::collections::BTreeMap; fn main() -> Result<(), Box<dyn std::error::Error>> { let connection_info: FalkorConnectionInfo = "falkor://127.0.0.1:6379".try_into()?; let client = FalkorClientBuilder::new() .with_connection_info(connection_info) .build()?; let mut graph = client.select_graph("typed_params_example"); // Start from a clean slate so the example is idempotent across runs. let _ = graph.delete(); // ── Before: hand-quoting and escaping every value yourself ────────────── // let mut params = HashMap::new(); // params.insert("title".to_string(), "'The Matrix'".to_string()); // manual quotes! // params.insert("year".to_string(), 1999.to_string()); // graph.query("CREATE (:Movie {title: $title, year: $year})").with_params(&params)... // ── After: typed values, encoding handled for you ─────────────────────── graph .query("CREATE (:Movie {title: $title, year: $year, rating: $rating})") .with_param("title", "The Matrix") .with_param("year", 1999) .with_param("rating", 8.7) .execute()?; // A string that would be a Cypher-injection attempt is stored as an inert literal. graph .query("CREATE (:Movie {title: $title, year: $year})") .with_param("title", "'; MATCH (n) DETACH DELETE n //") .with_param("year", 2003) .execute()?; // Collections work too: `WHERE x IN $list`. let mut titles = graph .query("MATCH (m:Movie) WHERE m.year IN $years RETURN m.title AS title ORDER BY m.year") .with_param("years", [1999, 2003]) .execute()?; for row in titles.data.by_ref() { // Read the column by its alias and convert it in one step. let title: String = row?.try_get("title")?; println!("matched: {title}"); } // Points can't be bound directly — pass the components as a map and wrap with `point()`. let coords = BTreeMap::from([("latitude", 32.07), ("longitude", 34.79)]); let mut located = graph .query("RETURN point($p)") .with_param("p", coords) .execute()?; if let Some(row) = located.data.next() { println!("point: {:?}", row?.get_at(0)); } graph.delete()?; Ok(()) }</code></pre>Source: examples/typed_params.rs</code></a> — compiled in CI. A few things I want to point at, because they're the whole point: with_param</code> takes typed Rust values. "The Matrix"</code> (a &str</code>), 1999</code> (an i64</code>), 8.7</code> (an f64</code>) — each is encoded as the correct Cypher literal. No quotes in your format string, because there is no format string.</li> Injection becomes a non-event. The line that binds "'; MATCH (n) DETACH DELETE n //"</code> as a title stores that whole thing as an inert string property. There is no parser context in which it can "break out," because it was never concatenated into the query text in the first place.</li> Collections just work. WHERE m.year IN $years</code> with [1999, 2003]</code> does what you'd hope — the array is bound as a Cypher list. Great for the IN</code>-list query you write fifteen times a week.</li> The type system catches the edges. Some values (a spatial point</code>) can't be bound as a raw literal, so the API makes you pass the components as a map and wrap them with point()</code>. That's the compiler steering you toward the one correct encoding instead of letting you guess.</li> </ul> The ergonomic version and the safe version are the same version. That's the bit I'm proud of: you don't choose safety here, you just write the obvious code and safety falls out. Why a graph client especially needs this</h2> Cypher is expressive, which is a polite way of saying there are a lot of places to inject. Node labels, relationship types, property maps, list predicates, path patterns. Bound parameters keep your data out of the query structure, permanently. Your query text becomes a fixed template the server can even cache and re-plan efficiently, and your values ride alongside it where they can't do any harm. It also makes the next feature possible. Once values are typed on the way in, it's a short hop to making results typed on the way out — which is exactly where Part 3</a> goes: rows that don't lie about what they contain. Why I keep betting on Rust for a graph database client Barak — Tue, 02 Jun 2026 00:00:00 +0000 Welcome to the dev log for the FalkorDB</a> Rust client. Over the next few posts I'm going to walk through a month of changes that took this crate from "it works" to "I'd actually hand this to a stranger." Type-safe parameters, header-aware rows, async streaming, an embedded server you can cargo run</code>, temporal values, retries, metrics, replica routing — the whole tour. But first, the obvious question: why pour this much effort into a client library, in Rust, for a graph database? Let me make the case. What FalkorDB is trying to be</h2> FalkorDB is a fast, low-latency graph database. Under the hood it represents the graph as sparse matrices and answers queries with linear algebra (GraphBLAS), which is a genuinely different bet from the pointer-chasing most graph databases do. The result is a database that stays quick when your graph gets big and your queries get hairy — exactly the workload that knowledge graphs and GenAI retrieval throw at you. A database is only as good as the distance between your code and its speed. You can have the fastest engine on earth, and if the client makes you hand-concatenate query strings and pattern-match untyped blobs, people will write slow, buggy code on top of it. The client is the product, as far as most developers ever experience it. That's the part I work on, and that's why I care about it this much. Why Rust</h2> I want a client that's fast, correct, and honest about failure — and Rust lets me have all three without picking two. Correctness you can feel at compile time. Rust's type system is the best code reviewer I've ever had. A whole category of "oops" — SQL/Cypher injection, mismatched result columns, forgetting that the network can fail — can be turned from runtime surprises into compile errors. Most of this series is really just me handing more of my mistakes to the compiler.</li> Performance without a runtime tax. Zero-cost abstractions mean the ergonomic API and the fast API are the same API. A typed row doesn't cost you a heap allocation it didn't need.</li> One library, two worlds. The same crate ships a blocking client and a tokio</code> async client with the same ergonomics. (More on how, and what it costs, in Part 4</a>.)</li> It embeds anywhere. Rust drops into CLIs, servers, and other languages' runtimes without dragging a VM along. We even ship an embedded FalkorDB server — see Part 5</a>.</li> </ul> Here's the whole thing in miniature — connect, query, iterate. This is the real examples/basic_usage.rs</code> from the repo: /* * Copyright FalkorDB Ltd. 2023 - present * Licensed under the MIT License. */ use falkordb::{FalkorClientBuilder, FalkorResult}; fn main() -> FalkorResult<()> { let client = FalkorClientBuilder::new() .with_connection_info("falkor://127.0.0.1:6379".try_into()?) .build()?; // Dataset is available in the 'resources' directory let mut graph = client.select_graph("imdb"); let mut cloned_graph = client.copy_graph("imdb", "imdb_clone")?; let mut res = graph.query("MATCH (a:actor) return a").execute()?; let mut clone_graph_res = cloned_graph.query("MATCH (a:actor) return a").execute()?; // Parses them one by one, to avoid unneeded performance hits assert_eq!(res.data.len(), 1317); assert_eq!(clone_graph_res.data.len(), 1317); if let (Some(orig), Some(cloned)) = (res.data.next(), clone_graph_res.data.next()) { println!("Original one: {orig:?}, Cloned one: {cloned:?}"); assert_eq!(orig, cloned); } // We have already parsed one result assert_eq!(res.data.len(), 1316); assert_eq!(clone_graph_res.data.len(), 1316); // more iterator usage: for (orig, cloned) in res.data.zip(clone_graph_res.data) { println!("Original one: {orig:?}, Cloned one: {cloned:?}"); assert_eq!(orig, cloned); } cloned_graph.delete()?; let res_again = graph.query("MATCH (a:actor) return a").execute()?; let as_vec = res_again.data.collect::<Vec<_>>(); assert_eq!(as_vec.len(), 1317); Ok(()) }</code></pre>Source: examples/basic_usage.rs</code></a> — compiled in CI. Notice what you don't see: no string-escaping, no unwrap()</code> confetti, no "parse this Vec<Vec<u8>></code> yourself." Reading a result is just iterating typed rows. We'll earn each of those niceties in later posts. The promise of this blog: the code can't lie</h2> I have a personal grudge against tech blogs whose code doesn't compile. You copy a snippet from a post, paste it in, and discover the API moved on two releases ago and nobody told the prose. So I built this blog to make that impossible. Every Rust sample you'll see is a real file in the repository — an examples/*.rs</code> program or a benches/*.rs</code> harness — that CI compiles on every push. At build time the site copies those exact files in and renders them. There is no hand-typed code on this blog. If a snippet is here, it built. flowchart LR A["examples/*.rs benches/*.rs"] -->|"just build-examples (CI)"| B["compiled, green check"] A -->|"blog-sync: byte-for-byte copy"| C["this blog post"] B -. guarantees .-> C </pre> The snippet you read is the file CI compiled.</figcaption> </figure> The same goes for numbers. When I show you a benchmark, it's a real criterion</code> harness, and the figures are a dated sample run you can reproduce with one command. No vibes-based performance claims. It's a small obsession, but it's the one that makes the rest of this series trustworthy. Next time, the first place I taught the compiler to catch my mistakes: query parameters. This is a developer dev log; opinions are mine and occasionally wrong in interesting ways. Corrections and heckling welcome on GitHub</a>. </blockquote>

FalkorDB-rs Dev Log

Read your writes: opt-in replica routing via Sentinel

Production-grade: retries, tracing spans, metrics, and error hints

Retries that can't duplicate a write</h2> Retries are a loaded gun. Re-issue a read and worst case you did some redundant work; re-issue a write and you might have just charged a customer twice. So the retry policy here has one inviolable rule: writes are never retried.</strong></p>

Typed mapping with serde, and temporal values that do real math

Batteries included: an embedded FalkorDB you can cargo run

Async all the way down: streaming results and connection multiplexing

Rows that don't lie: header-aware, fallible result iteration

The new shape</h2> Two changes, and they compose:</p> Result sets are header-aware.</strong> A row knows its column names, so you read by alias — row.try_get("year")</code> — not by a magic index.</li>

Stop hand-quoting Cypher: type-safe, injection-proof parameters

Why I keep betting on Rust for a graph database client