Quick start
The whole loop, end to end:
Prerequisites
-
Rust 1.87 or newer (
rust-versioninCargo.toml). -
just — the tool the recipes call:
cargo install just -
make (inside Git Bash on Windows) and Python 3 — the official DuckDB
extension-ci-toolsbuild/test flow, whichjust buildruns under the hood (make configure+make debug).just testuses the same flow. -
A DuckDB binary 1.3 or newer (
duckdbonPATH, or point at it withjust DUCKDB=/path/to/duckdb …).
1. Get the source
git clone https://github.com/shijianjs/duckfn-kuva
cd duckfn-kuva
The extension name is fixed here: duckfn_kuva is the entry-point symbol and the artifact file name, so
it has to read identically in Cargo.toml, the Makefile, src/extension/mod.rs, the Justfile and the CI
workflow. Only a project that starts from
duckfn-extension-template changes it, with
just rename <name>; the five places and the rules are in AGENTS.md.
2. Build
just build # = make configure && make debug
The artifact is build/debug/duckfn_kuva.duckdb_extension. There is no C++ step and no local DuckDB
build: the extension is compiled against DuckDB's headers and dispatches through its API table when it
is loaded.
3. Load and call it
just repl # a DuckDB REPL with the extension already loaded
-- or by hand; -unsigned is required for a locally built extension
duckdb -unsigned -c "LOAD './build/debug/duckfn_kuva.duckdb_extension';"
kuva_render, running right here — the site preloads the extension from the repository's latest release,
so no local LOAD is needed here (a hand-built extension still needs -unsigned; see the traps below).
Click Run on any block and the chart is drawn in the result area — fullscreen is where zoom and pan
live, and the Table tab always holds the raw SVG.
-- a scatter plot
SELECT kuva_render(to_json({
'series': [{'type': 'scatter', 'data': array_agg({'x': x, 'y': y})}]
})) AS chart
FROM read_csv_auto('{{DFK_BASE_URL}}data/scatter.tsv');
-- one line per condition, overlaid on one layout
SELECT kuva_render(to_json({
'series': list({'type': 'line', 'data': pts, 'legend': g} ORDER BY g)
})) AS chart
FROM (
SELECT "group" AS g, array_agg({'x': time, 'y': value} ORDER BY time) AS pts
FROM read_csv_auto('{{DFK_BASE_URL}}data/measurements.tsv')
GROUP BY "group"
);
The failure path is a runnable block too — it declares that it is supposed to fail:
SELECT kuva_render('{"series":[]}'); -- error: a chart needs at least one series
A single query from the command line, without a REPL:
just sql "SELECT left(kuva_render('{\"series\":[{\"type\":\"scatter\",\"data\":[{\"x\":1,\"y\":2},{\"x\":3,\"y\":4}]}]}'), 4)"
4. Run the tests
just test # make configure + make debug + make test
The faster loop is in Testing.
Traps
-unsignedis mandatory when you load a locally built extension. Without it DuckDB refuses the file.- The artifact file name must stay
<extension name>.duckdb_extension. DuckDB finds the entry-point symbol through the file name, so a copy calledwin.duckdb_extensionfails withdid not contain function "duckfn_kuva_init_c_api". make testdoes not rebuild. After changing Rust code runjust ci-build(ormake debug) first, otherwise the tests run against the previous artifact.
One more, on Windows: if make debug reports the artifact is in use, a DuckDB process is
holding build/debug/duckfn_kuva.duckdb_extension (usually a just repl left open) — close that
process and rebuild. A .duckdb_extension is not a renamed DLL: DuckDB's metadata lives at the end of
the file, so copying a DLL over it produces The metadata at the end of the file is invalid.