DuckDB 命令行与 SQL 工具详解
详解 DuckDB 官方命令行工具 duckdb_cli 的完整用法：启动选项（-c/-s/-cmd/-mode/-maxrows）、dot 命令（.mode/.columns/.maxrows/.import/.output/.schema/.tables）、duckbox 矩形渲染、以及 READ 直接解析 CSV/JSON 的 SQL 工具 read_csv/read_json 与 .import 导入。基于 DuckDB v1.5.6 实测。
DuckDB 命令行与 SQL 工具详解
目标：掌握 DuckDB 官方命令行
duckdb（CLI）与内置 SQL 数据工具。DuckDB 是嵌入式、单文件的分析型（OLAP）数据库，CLI 既是交互式 shell，也可直接传入 SQL 批处理；并通过read_csv/read_json/read_parquet等表函数直接读取外部数据。本文全部命令基于 DuckDB v1.5.6 实测。
环境信息
| 信息项 | 值 |
|---|---|
| DuckDB 版本 | v1.5.6（Variegata） |
| 命令行 | /usr/local/bin/duckdb（单文件二进制） |
| 操作系统 | Ubuntu 22.04.5 LTS |
| 演示库 | /tmp/e.db |
一、版本查看
duckdb --version
duckdb -c "SELECT version() AS v;"
实测输出：
v1.5.6 (Variegata) 069cc9f9b5
SQL 内版本查询（duckbox 矩形渲染）：
┌─────────┐
│ v │
│ varchar │
├─────────┤
│ v1.5.6 │
└─────────┘
二、命令行用法与启动选项
Usage: duckdb [OPTIONS] FILENAME [SQL]
FILENAME：数据库文件名，不存在则自动创建；缺省默认内存库:memory:。- 末尾可带
SQL：执行后退出（批处理）。
duckdb --help 常用选项（节选）：
| 选项 | 作用 |
|---|---|
-c/--command COMMAND | 执行一条 SQL 后退出 |
-s COMMAND | 执行一条 SQL 后退出（同上） |
-cmd COMMAND | 在读 stdin 前先执行（交互批处理组合） |
-f FILENAME | 读取并执行 SQL 文件后退出 |
-init FILENAME | 启动前读取初始化文件 |
-mode MODE | 设输出模式（list/column/csv/json/jsonlines…） |
-header / -noheader | 开 / 关列名表头 |
-maxrows N | 最大显示行数（duckbox，默认 40） |
-separator SEP | 设列分隔符（默认 ` |
-nullvalue TEXT | NULL 显示文本（默认 NULL） |
-readonly | 只读打开 |
-safe | 安全模式 |
-version | 版本 |
-batch / -interactive | 批量 / 交互 I/O |
单条 SQL 执行
duckdb e.db "SELECT 1+1 AS s;"
duckdb e.db -c "SELECT count(*) FROM emp;"
-c 与 -s 等价；多条命令可用 -cmd 串联：
duckdb e.db -cmd ".mode json" -cmd "SELECT 1 AS a, 'x' AS b;"
实测（json 模式）：
[{"a":1,"b":"x"}]
三、dot 命令（点命令）
DuckDB CLI 的 dot 命令以 . 开头。duckdb :memory: ".help" 查看全部。核心命令：
| 命令 | 作用 |
|---|---|
.tables ?PATTERN? | 列出表 |
.schema ?PATTERN? | 显示建表语句 |
.databases | 列出所有库 |
.columns | 列式渲染结果 |
.rows | 行式渲染结果（默认） |
.mode MODE | 输出模式：list/column/box/csv/json/lines 等 |
| `.headers on | off` |
.maxrows N | 最大显示行数（默认 40） |
.maxwidth N | 最大渲染宽度 |
.import FILE TABLE | 把 CSV 导入表 |
.output ?FILE? | 输出到文件 |
.once ?FILE? | 下一条命令输出到文件 |
.dump ?TABLE? | 导出为 SQL |
.read FILE | 执行 SQL 文件 |
| `.timer on | off` |
.version | 版本 |
.exit / .quit | 退出 |
💡 DuckDB 与 SQLite 的 CLI 相似但输出默认用 duckbox（矩形表格） 而非列表；若需竖线分隔旧风格，用
.mode list或.mode csv。
示例：查看库结构与导出
duckdb e.db ".tables"
duckdb e.db ".schema"
duckdb e.db -cmd ".mode csv" -cmd "SELECT * FROM emp;"
四、duckbox 渲染与模式
默认结果以矩形框呈现，含类型信息：
SELECT id, name FROM emp ORDER BY id LIMIT 2;
┌───────┬─────────┐
│ id │ name │
│ int32 │ varchar │
├───────┼─────────┤
│ 1 │ alice │
│ 2 │ bob │
└───────┴─────────┘
切换模式：
duckdb e.db ".mode list" # 竖线分隔
duckdb e.db ".mode csv" # CSV（便于管道）
duckdb e.db ".mode json" # JSON 数组
duckdb e.db ".mode lines" # 每行 key:value
五、直接读取外部数据的 SQL 工具
DuckDB 强大的表函数可在不先导入的情况下直接查询 CSV / JSON / Parquet 文件，自动推断 schema：
5.1 read_csv
SELECT * FROM read_csv('/tmp/emp.csv', header=true);
┌───────┬─────────┐
│ id │ name │
│ int64 │ varchar │
├───────┼─────────┤
│ 1 │ alice │
│ 2 │ bob │
└───────┴─────────┘
5.2 read_json
SELECT * FROM read_json('/tmp/emp.json');
自动将 JSON 数组解析为行。
5.3 read_parquet / read_parquet(glob)
SELECT count(*) FROM read_parquet('/tmp/emp.parquet');
Parquet 是列式格式，与 DuckDB 契合，导入即查。
六、导入：.import 与 CREATE TABLE AS
把文件导入为表：
duckdb i.db ".mode csv" ".import /tmp/emp.csv t" "SELECT count(*) FROM t;"
实测返回 2。也可用 SQL 建表：
CREATE TABLE emp AS SELECT * FROM read_csv('/tmp/emp.csv', header=true);
七、导出与流式
DuckDB CLI 可与 Linux 管道配合做流式分析：
cat /tmp/emp.csv | duckdb -csv :memory: "SELECT * FROM read_csv_auto('/dev/stdin');"
八、常见问题（FAQ）
1. library_version() 报错？
集合仅 version() 可用，duckdb --version 查 CLI 版本。
2. .commands 不存在？
DuckDB 用 .help 而非 .commands；点命令列表见上文。
3. 结果被截断 ... (40 rows)？
.maxrows 0 或调大显示全部行。
4. read_csv 报类型推断不一致？
同列出现数值与文本时推断为 VARCHAR。可用 read_csv(..., types={'id':'INTEGER'}) 指定。
九、小结
DuckDB CLI 与 SQLite 类似但默认 duckbox 渲染、强项是直接 read_csv/read_json/read_parquet 即时分析与 .import/.mode 多格式输出，适合数据分析与 ETL。后续结合《DuckDB 配置与 PRAGMA 详解》调优线程/内存，《DuckDB 备份与数据导入导出》做持久化与迁移。