基于 DB::DuckDB 的 TUI ETL 工具设计分析

分析对象：DB::DuckDB 0.8.3（提交 e0b1670） 运行时：Rakudo 2026.09 / DuckDB v2.0.0-dev1（WSL Ubuntu） 日期：2026-10-30 结论性质：设计建议。标注 [实测] 的条目有本机运行记录，见附录 A；未标注的是基于代码/文档的推断。

0. 结论先行

基于 DB::DuckDB 做 TUI ETL，有三个硬约束决定架构：

1. 数据平面必须留在 DuckDB 里。 Raku 只负责编排 SQL 和渲染界面。仓库实测 COPY 写 Parquet 约 0.03 µs/行，而 execute-many / appender 约 11.3 µs/行（约 400 倍差距）；逐行进 Raku 还会触发 GC，TUI 会卡。

2. DuckDB 文件库是跨进程独占的。 [实测] 进程 A 打开 /tmp/lock.duckdb 后，进程 B 用 DB::DuckDB.new(path => ...) 直接失败；手写 duckdb_open_ext(..., access_mode=READ_ONLY) 在 writer 持锁时也返回失败。 所以 v1 不要设计成“TUI 进程 + 独立 worker 进程同时开同一个库”。

3. TUI 线程不能碰慢查询。 所有可能超过 ~50 ms 的操作（schema 推断、预览、执行）走后台线程 + 独立 connection，UI 只消费事件和快照。

推荐 v1 形态：

单进程 TUI + 每个任务一条独立 connection + SQL-first 执行引擎 + Terminal::UI 做界面基座。

等需要崩溃隔离时，再加“worker 进程独占数据库、TUI 不打开数据文件”的模式。

1. 产品边界与交互设计

1.1 范围

先做“本机单用户、文件 / DuckDB 为源、Parquet / CSV / 表为目标”的 ETL：

• 不做调度平台

• 不做多租户

• 不做远程编排

• 不做通用工作流 DAG（v1 线性步骤；后续再加 depends_on）

核心闭环：

选源 → 推断 schema → 预览 → 定义步骤 → 试跑 → 看进度/日志 → 落表/落文件 → 存 pipeline

1.2 五屏

键位用 vim 风格 + 功能键；: 命令面板；破坏性操作（覆盖表、删除 pipeline）必须 ui.alert 二次确认。

1.3 主布局

┌ ETL ─ nightly_orders ─────────────────────────── ▶ running 4/7 ─┐
│ Pipelines     │ Steps                          │ Run            │
│ ▸ nightly     │ 1 extract  csv  raw/*.csv  ok  │ 00:01:23       │
│ ▸ daily       │ 2 clean    sql              ok  │ 1.24M rows     │
│ Sources       │ 3 join     customers       run │ 12.3k rows/s   │
│ ▸ raw/orders  │ 4 load     parquet         ·   │                │
│ ▸ mart/orders │                                │ Preview        │
│               │ SQL  select id, amount ...     │ id  amount     │
│               │      from extract where ...    │ 1   12.50      │
├───────────────┴────────────────────────────────┴────────────────┤
│ F1 help  F2 run  F3 cancel  F5 edit  p preview  : cmd  q quit   │
└─────────────────────────────────────────────────────────────────┘

最小终端建议 100×28；低于阈值降级为单栏堆叠。

2. 总体架构

关键点：

• 一个 DB::DuckDB 实例打开数据文件；$db.connect 给每个 job 一条 connection。[实测] 同一进程 4 条 connection 并行查询正常，session 连接不受影响。

• UI 自己的 session connection 只做 catalog / 小预览；不要和 job 共用。

• history 用另一个 .duckdb 文件（如 ~/.local/share/ducketl/history.duckdb），避免和数据库抢锁，也避免运行历史污染业务库。

• 任务线程：start { ... } + Channel 事件。写目标串行化（每个目标表一把 Lock::Async），读可以并行；DuckDB 同进程多连接支持一写多读。

• 可选隔离模式：--isolated 时 worker 进程独占数据文件，TUI 只通过 JSONL 收事件；此时 TUI 不能同时浏览数据库。作为后续能力，不进 v1 关键路径。

2.1 为什么不是“UI 进程 + worker 进程”

[实测] 跨进程打开直接被文件锁拒绝。可行的多进程方案只有两种：

1. worker 独占数据库，TUI 完全不开数据文件（通过 IPC 查元数据/预览）——实时浏览体验差。

2. 数据文件拆成两个（只读快照 + 写入库）——同步复杂，v1 不值得。

所以 v1 用单进程；等 M3 再评估隔离模式。

3. 数据模型与执行引擎

3.1 Pipeline 文件格式

建议 JSON 作为 canonical（JSON::Fast 可读写）；YAML 只做导入。

原因：Raku 生态有 YAML::Parser::LibYAML，但 [实测] zef 生态中没有可用的 YAML::Dumper；TUI 内保存 YAML 需要自己写受限 emitter。JSON 更省事。

{
  "name": "nightly_orders",
  "defaults": { "threads": 8, "memory_limit": "2GB" },
  "steps": [
    {
      "id": "extract",
      "type": "source",
      "format": "csv",
      "path": "raw/orders_*.csv",
      "options": { "header": true, "delim": ",", "sample_size": 100000 }
    },
    {
      "id": "clean",
      "type": "sql",
      "sql": "select id, customer_id, cast(amount as decimal(18,2)) amount, cast(created_at as timestamp) created_at from extract where amount is not null"
    },
    {
      "id": "load",
      "type": "sink",
      "target": "mart.orders",
      "mode": "upsert",
      "key": ["id"],
      "watermark": "created_at"
    }
  ]
}

步骤类型先做四种：

3.2 SQL 生成

source：

create or replace temp table _etl_extract as
select * from read_csv_auto(?, header=true, delim=',', sample_size=100000);

路径必须走参数绑定（read_csv_auto(?)），不要拼字符串。COPY TO 的目标路径才需要字面量，复用仓库 DB::DuckDB::Parquet 里的 literal / identifier 转义逻辑。

中间步骤默认物化到 temp table，这样每步可预览、可计数、可断点调试：

create or replace temp table _etl_clean as
select ... from _etl_extract where ...;

对性能敏感的 pipeline 提供 "materialize": false，把整条链压成一个 CTE / 单条 CREATE TABLE AS SELECT。

默认策略：source / sink 物化，中间 sql 步骤可配置。

sink：

-- 全量
create or replace table mart.orders as select * from _etl_clean;

-- upsert（本机 v2.0.0-dev1 实测 ON CONFLICT 可用）
insert into mart.orders select * from _etl_clean
on conflict (id) do update set ...;

Parquet 直接用驱动现成方法：

$db.write-parquet('out/orders.parquet', 'select * from _etl_clean',
                  :sql, :compression<zstd>);

CSV 用 SQL：

copy (select * from _etl_clean) to 'out.csv' (header, delimiter ',')

文件 sink 一律写临时文件再原子 rename，避免半成品。

3.3 运行元数据

用 DuckDB 自己存：

_etl.runs(run_id, pipeline, started_at, finished_at, status, rows, error)
_etl.steps(run_id, step_id, status, started_at, finished_at, rows, sql, error)
_etl.watermarks(pipeline, step_id, column, value)

状态机：

pending → running → ok | failed | canceled | skipped

失败步骤保留已物化的 temp 表，方便在 UI 里查看；取消时 rollback 当前事务并 drop temp 表。

3.4 取消与进度

• 取消：duckdb_interrupt 已经在 lib/DB/DuckDB/Native.rakumod 绑定（第 333 行），但没有公开方法。加 Connection.interrupt，从 UI 线程对 job connection 调用；这是 v1 取消按钮的唯一正确实现。进程级 kill 只作为兜底。

• 进度：duckdb_query_progress 存在于 libduckdb 2.0（duckdb.h 第 3716 行），但返回结构体 by value；驱动刻意回避 by-value 结构体返回（README Design notes），建议照 duckdb-result-shim.c 写一个小 shim 返回指针。

• 没有 progress 的语句（如 COPY）用“心跳 + 已完成步骤 + 行数”展示，不要假装有精确百分比。

• 事件协议（进程内 Channel，或隔离模式下的 JSONL）：

{"run":"20261030-1201","step":"load","phase":"progress","rows":1240000,"elapsed_ms":83000}

3.5 增量与校验

• 水位：where created_at > (select value from _etl.watermarks where ...)；成功提交后再更新水位。

• upsert：ON CONFLICT 已实测可用；MERGE 未验证，不要先承诺。

• 校验：SUMMARIZE SELECT * FROM _etl_clean 已实测可用，能直接给出 min / max / approx_unique / null_percentage，适合做“数据质量”面板。

• dry run：EXPLAIN + SELECT * FROM (<sql>) LIMIT 0，不执行数据。

4. TUI 实现方案

4.1 选型

4.2 关键做法

• 纯函数渲染：每个 widget 提供 render($state, $width, $height --> List[Str])，输出直接 $pane.put(@lines)。这样 80×24 / 120×40 / CJK 都能做 golden test，不需要 PTY。

• 虚拟表格：只渲染视口。预览查询固定 LIMIT 100（或 keyset 分页）；流式预览用 :stream 读第一块（README 实测首块 12–20 ms）后立即 free，绝不对全量结果调 .hashes。

• SQL 编辑器：Raku 没有成熟的 TUI 代码编辑器。短 SQL 用单行 buffer + 自绘光标；长 SQL 用 ui.pause-and-do 调 $EDITOR / $VISUAL，回来重新解析。这是最省事且可靠的做法。

• 输入框：Terminal::UI 的 Input 只提供原始按键，没有行编辑；自己实现一个 50 行的单行编辑器（插入 / 删除 / Home / End / 粘贴）即可。不要把 Linenoise / Readline 塞进全屏 TUI，它们会抢 tty。

• 重绘节奏：10–20 Hz；事件合并，只有 dirty pane 重绘；日志 pane 用 5k 行环形缓冲。

• 异常安全：LEAVE / CX::Done 里 ui.shutdown，否则崩溃后终端留在 raw mode。

• 宽度：CJK 宽字符会让表格错位。Terminal::UI 声称 Unicode 兼容，但先用中文列名 / 中文值做验收；不行就自带一张 wcwidth 表（约 100 行）。

• 兼容性：NO_COLOR、Terminal::Capabilities 判断真彩色 / 256 色；边框提供 ASCII 回退。

4.3 线程模型

UI 线程：按键 → 状态机 → 渲染快照；只做 <16ms 的工作
Job 线程：独立 connection；执行 SQL；向 Channel 发事件
Preview 线程：LIMIT 查询；可取消；结果只回传 ≤200 行

DB::DuckDB::Result / Chunk 不要跨线程传递；chunk 只在下一次 pull 前有效。事件里只传普通 Hash / List。

5. 库清单

5.1 必需

5.2 按需

5.3 不推荐 / 不可用

5.4 依赖声明

建议 独立发行版 App::DuckETL 依赖 DB::DuckDB，不要把 TUI 依赖塞进驱动本体。

"depends": [
  "DB", "DB::DuckDB", "Alien::Libduckdb",
  "Terminal::UI", "Terminal::ANSIColor", "Terminal::Size",
  "Terminal::Capabilities", "JSON::Fast", "Log::Async"
]

6. 需要给驱动补的 API

扩展情况（[实测] duckdb_extensions()）：已装 core_functions, icu, json, parquet；没有 httpfs / sqlite / postgres / excel。

远程 HTTP、SQLite、Postgres、Excel 源需要 INSTALL/LOAD 扩展，先按“可选插件”设计，并单独验证网络与扩展加载，不要写进 v1 的核心路径。

7. 推荐目录结构

ducketl/
├── META6.json
├── bin/ducketl
├── lib/App/DuckETL.rakumod
├── lib/App/DuckETL/CLI.rakumod
├── lib/App/DuckETL/Config.rakumod
├── lib/App/DuckETL/Pipeline.rakumod
├── lib/App/DuckETL/Planner.rakumod
├── lib/App/DuckETL/Executor.rakumod
├── lib/App/DuckETL/Duck.rakumod
├── lib/App/DuckETL/Run.rakumod
├── lib/App/DuckETL/Store.rakumod
├── lib/App/DuckETL/TUI.rakumod
├── lib/App/DuckETL/TUI/Screen/Dashboard.rakumod
├── lib/App/DuckETL/TUI/Screen/Sources.rakumod
├── lib/App/DuckETL/TUI/Screen/Pipeline.rakumod
├── lib/App/DuckETL/TUI/Screen/Run.rakumod
├── lib/App/DuckETL/TUI/Screen/Data.rakumod
├── lib/App/DuckETL/TUI/Widget/Grid.rakumod
├── lib/App/DuckETL/TUI/Widget/Form.rakumod
├── lib/App/DuckETL/TUI/Widget/Editor.rakumod
├── lib/App/DuckETL/TUI/Widget/LogPane.rakumod
├── t/
└── examples/pipelines/nightly_orders.json

职责边界：

• Pipeline：JSON 模型 + 校验 + 步骤引用解析

• Planner：步骤 → SQL（纯函数，golden test 的重点）

• Executor：事务、取消、进度、事件

• Duck：连接管理、catalog、schema 推断、分页预览

• Store：history / watermarks

• TUI：只依赖 Run 事件和 Duck 的只读快照

8. 里程碑

9. 主要风险与对策

10. 待拍板的问题

附录 A：本机实测记录

环境：Rakudo 2026.09，DuckDB v2.0.0-dev1，WSL Ubuntu，DB::DuckDB 0.8.3 源码树。

A.1 SQL 能力

A.2 并发与锁

A.3 驱动 API

A.4 库生态检索

zef search 结果（2026-10-30）：

附录 B：复现实验的最小脚本

use DB::DuckDB;

my $db = DB::DuckDB.new;
say $db.query('select version()').value;

# CSV / JSON / SUMMARIZE / CTAS / ON CONFLICT / COPY TO
$db.execute("create table t as select * from read_csv_auto(?)", 'a.csv');
say $db.query("summarize select * from t").arrays.elems;
$db.execute("copy t to '/tmp/out.parquet' (format parquet)");
say $db.query("select count(*) from read_parquet('/tmp/out.parquet')").value;

跨进程锁复现：

# A：打开文件库并持有
raku -Ilib -e 'use DB::DuckDB; my $db = DB::DuckDB.new(path => "/tmp/lock.duckdb"); $db.execute("create table if not exists t(x int)"); sleep 6'

# B：同时打开
raku -Ilib -e 'use DB::DuckDB; my $ok = try { DB::DuckDB.new(path => "/tmp/lock.duckdb").query("select 1"); True } // False; say $ok'
# => False

附录 C：一句话落地顺序

先写 M0 的 SQL 生成器 + ducketl run，用真实 CSV / Parquet 跑通；再套 Terminal::UI 的三栏壳；最后补编辑器、进度和增量。

TUI 不是难点，**锁模型和“数据不过 Raku”**才是这个项目的生死线。