Skip to main content

Quick start

The whole loop, end to end:

Prerequisites​

  • Rust 1.87 or newer (rust-version in Cargo.toml).

  • just — the tool the recipes call:

    cargo install just
  • make (inside Git Bash on Windows) and Python 3 — the official DuckDB extension-ci-tools build/test flow, which just build runs under the hood (make configure + make debug). just test uses the same flow.

  • A DuckDB binary 1.3 or newer (duckdb on PATH, or point at it with just 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​

Three things that look like bugs and are not
  • -unsigned is 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 called win.duckdb_extension fails with did not contain function "duckfn_kuva_init_c_api".
  • make test does not rebuild. After changing Rust code run just ci-build (or make 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.