快速开始
整个流程,从头到尾:
前置条件
-
Rust 1.87 或更新(
Cargo.toml里的rust-version)。 -
just —— recipe 会调用它:
cargo install just -
make(Windows 上要在 Git Bash 里跑)与 Python 3 —— 官方 DuckDB
extension-ci-tools的构建 / 测试流程,just build底层就是它(make configure+make debug),just test走的也是同一套。 -
一个 DuckDB 1.3 或更新的可执行文件(
duckdb在PATH里,或者用just DUCKDB=/path/to/duckdb …指定)。
1. 拉源码
git clone https://github.com/shijianjs/duckfn-kuva
cd duckfn-kuva
这里扩展名是固定的:duckfn_kuva 既是入口点符号、也是产物文件名,所以 Cargo.toml、Makefile、
src/extension/mod.rs、Justfile 与 CI 工作流里的写法必须逐字一致。只有从
duckfn-extension-template 起的新项目才需要
改它,用 just rename <名字>;那五处位置与规则见 AGENTS.md。
2. 构建
just build # = make configure && make debug
产物是 build/debug/duckfn_kuva.duckdb_extension。没有 C++ 这一步,也不需要本地编译 DuckDB:扩展
只用到 DuckDB 的头文件,加载时通过它的 API 表分发。
3. 加载并调用
just repl # 已经 LOAD 好扩展的 DuckDB REPL
-- 或者手动来;本地构建的产物必须加 -unsigned
duckdb -unsigned -c "LOAD './build/debug/duckfn_kuva.duckdb_extension';"
kuva_render,就地就能跑 —— 站点从仓库的最新 Release 预加载了这个扩展,这里不用写 LOAD(本地自己
构建的产物仍然要加 -unsigned,见下面的几个坑)。点任意块上的 执行,图就画在结果区里 —— 缩放与
平移在全屏里,Table 那个页签里始终是原始的 SVG。
-- 一张散点图
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');
-- 每个 condition 一条折线,叠在同一套布局上
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"
);
失败路径同样是个可运行块 —— 它自己声明了「应该失败」:
SELECT kuva_render('{"series":[]}'); -- 报错:一张图至少要有一个 series
不进 REPL、只跑一条语句:
just sql "SELECT left(kuva_render('{\"series\":[{\"type\":\"scatter\",\"data\":[{\"x\":1,\"y\":2},{\"x\":3,\"y\":4}]}]}'), 4)"
4. 跑测试
just test # make configure + make debug + make test
更快的迭代方式见测试。
几个坑
- 本地构建的产物加载时必须加
-unsigned,不加 DuckDB 会直接拒绝这个文件。 - 产物文件名必须保持
<扩展名>.duckdb_extension。 DuckDB 是按文件名去找入口点符号的,复制成win.duckdb_extension会报did not contain function "duckfn_kuva_init_c_api"。 make test不会自动重新构建。 改完 Rust 先跑just ci-build(或make debug),否则测试跑的 还是上一次的产物。
Windows 上还有一条:如果 make debug 报产物被占用,说明有 DuckDB 进程正拿着
build/debug/duckfn_kuva.duckdb_extension(多半是没关的 just repl)—— 关掉那个进程重新构建即可。
.duckdb_extension 不是改了名的 DLL:DuckDB 的元数据在文件尾,直接 Copy-Item 一个 DLL 过去会报
The metadata at the end of the file is invalid。