Dot 命令

Goose CLI 客户端支持 dot 命令。使用此类命令时，需以句点（.）开头，后面紧跟要执行的命令名。 命令的附加参数写在命令后方，以空格分隔。若参数中包含空格，可使用单引号或双引号包裹。 dot 命令必须写在单行内，且句点前不能有空白字符。行尾不需要分号。可通过 .help 查看可用命令。

Dot 命令列表

命令	说明
.bail ⟨on/off⟩	遇到错误后停止。默认：off
.binary ⟨on/off⟩	Turn binary output on or off. Default: off
.cd ⟨DIRECTORY⟩	将工作目录切换到 DIRECTORY
.changes ⟨on/off⟩	显示 SQL 影响的行数
.columns	以按列方式渲染查询结果
.constant ⟨COLOR⟩	设置常量值的语法高亮颜色
.constantcode ⟨CODE⟩	设置常量值语法高亮使用的终端代码
.databases	列出已附加数据库的名称和文件
.echo ⟨on/off⟩	打开或关闭命令回显
.exit ⟨CODE⟩	以返回码 CODE 退出程序
.headers ⟨on/off⟩	打开或关闭表头显示。不适用于 duckbox 模式
.help ⟨-all⟩ ⟨PATTERN⟩	显示 PATTERN 的帮助文本
.highlight ⟨on/off⟩	打开/关闭 shell 中的语法高亮。详见查询语法高亮配置
.highlight_colors ⟨COMPONENT⟩ ⟨COLOR⟩	配置各组件颜色（仅 duckbox）。详见结果语法高亮配置
.highlight_results ⟨on/off⟩	打开/关闭结果表高亮（仅 duckbox）。详见结果语法高亮配置
.import ⟨FILE⟩ ⟨TABLE⟩	将 FILE 中数据导入 TABLE
.indexes ⟨TABLE⟩	显示索引名称
.keyword ⟨COLOR⟩	设置关键字语法高亮颜色
.keywordcode ⟨CODE⟩	设置关键字语法高亮使用的终端代码
.large_number_rendering ⟨all/footer/off⟩	切换大数字可读渲染（仅 duckbox，默认：footer）
.log ⟨FILE/off⟩	打开或关闭日志。FILE 可为 stderr / stdout
.maxrows ⟨COUNT⟩	设置显示的最大行数。仅适用于 duckbox 模式
.maxwidth ⟨COUNT⟩	设置最大字符宽度。0 表示终端宽度。仅适用于 duckbox 模式
.mode ⟨MODE⟩ ⟨TABLE⟩	设置输出模式
.multiline	设置为多行模式（默认）
.nullvalue ⟨STRING⟩	使用 STRING 替代 NULL 值。默认：NULL
.once ⟨OPTIONS⟩ ⟨FILE⟩	仅将下一条 SQL 命令输出到 FILE
.open ⟨OPTIONS⟩ ⟨FILE⟩	关闭当前数据库并重新打开 FILE
.output ⟨FILE⟩	输出到 FILE；若省略 FILE 则输出到 stdout
.print ⟨STRING...⟩	原样打印 STRING
.progress_bar ⟨COMPONENT⟩	设置进度条组件样式
.prompt ⟨OPTIONS⟩ ⟨CONTINUE⟩	替换标准提示符
.quit	退出程序
.read ⟨FILE⟩	从 FILE 读取输入
.rows	以按行方式渲染查询结果（默认）
.safe_mode	启用安全模式
.schema ⟨PATTERN⟩	显示匹配 PATTERN 的 CREATE 语句
.separator ⟨COL⟩ ⟨ROW⟩	修改列分隔符和行分隔符
.shell ⟨CMD⟩ ⟨ARGS...⟩	在系统 shell 中执行 CMD 和 ARGS...
.show	显示各项设置当前值
.singleline	设置为单行模式
.system ⟨CMD⟩ ⟨ARGS...⟩	在系统 shell 中执行 CMD 和 ARGS...
.tables ⟨TABLE⟩	列出与 TABLE（LIKE 模式）匹配的表名
.timer ⟨on/off⟩	打开或关闭 SQL 计时器。以 ; 分隔但未换行分隔的 SQL 语句会被合并计时
.width ⟨NUM1⟩ ⟨NUM2⟩ ...	设置列式输出的最小列宽

使用 .help 命令

可将文本作为第一个参数传入，用于筛选 .help 输出。

.help m

.maxrows COUNT           Sets the maximum number of rows for display (default: 40). Only for duckbox mode.
.maxwidth COUNT          Sets the maximum width in characters. 0 defaults to terminal width. Only for duckbox mode.
.mode MODE ?TABLE?       Set output mode

.output：将结果写入文件

默认情况下，Goose CLI 会将结果输出到终端标准输出。你可以通过 .output 或 .once 修改此行为。 将目标文件路径作为参数传入即可。.once 仅将下一次结果输出到文件，随后恢复到标准输出； .output 则会将后续所有输出都重定向到该文件。注意每次结果都会覆盖目标文件原内容。 若要恢复标准输出，执行不带文件参数的 .output。

在此示例中，先将输出格式改为 markdown，再指定 Markdown 文件作为输出目标， Goose 会将 SQL 语句结果写入该文件。随后通过不带参数的 .output 恢复到标准输出。

.mode markdown
.output my_results.mdx
SELECT 'taking flight' AS output_column;
.output
SELECT 'back to the terminal' AS displayed_column;

此时文件 my_results.mdx 内容如下：

| output_column |
|---------------|
| taking flight |

终端随后显示：

|   displayed_column   |
|----------------------|
| back to the terminal |

常见输出格式是 CSV（逗号分隔值）。Goose 支持使用 SQL 语法导出为 CSV 或 Parquet， 但也可按需使用 CLI 专用命令写出 CSV。

.mode csv
.once my_output_file.csv
SELECT 1 AS col_1, 2 AS col_2
UNION ALL
SELECT 10 AS col1, 20 AS col_2;

文件 my_output_file.csv 将包含：

col_1,col_2
1,2
10,20

向 .once 传入特定选项（flag）后，查询结果还可以写入临时文件并自动用系统默认程序打开。 -e 用于文本文件（默认文本编辑器打开），-x 用于 CSV 文件（默认电子表格程序打开）。 这对于详细检查查询结果很有帮助，尤其适用于较大的结果集。.excel 等价于 .once -x。

.once -e
SELECT 'quack' AS hello;

结果会在系统默认文本编辑器中打开，例如：

提示：macOS 用户可使用 pbcopy 将结果复制到剪贴板， 方式是通过管道把 .once 输出给 pbcopy：.once |pbcopy

与 .headers off 和 .mode lines 组合使用通常效果更好。

查询数据库 Schema

所有 Goose 客户端都支持使用 SQL 查询数据库 schema， 但 CLI 还提供了额外的 dot 命令，便于理解数据库内容。 .tables 会返回数据库中的表列表。它可选接收一个参数，按 LIKE 模式过滤结果。

CREATE TABLE swimmers AS
SELECT 'duck' AS animal;
CREATE TABLE fliers AS
SELECT 'duck' AS animal;
CREATE TABLE walkers AS
SELECT 'duck' AS animal;
.tables

fliers
swimmers  walkers

例如，要筛选仅包含 l 的表，可使用 LIKE 模式 %l%。

.tables %l%

fliers
walkers

.schema 命令会显示定义数据库 schema 的全部 SQL 语句。

.schema

CREATE TABLE fliers
(
    animal VARCHAR
);
CREATE TABLE swimmers
(
    animal VARCHAR
);
CREATE TABLE walkers
(
    animal VARCHAR
);

进度条

Goose CLI 客户端的进度条支持通过组件进行自定义。

.progress_bar 命令支持 --add 与 --clear 参数，用于添加和移除组件。

具体用法见下方示例。

配置进度条显示

检查进度条是否启用：

SELECT *
FROM goose_settings()
WHERE name = 'enable_progress_bar';

检查触发进度条显示所需的最小查询时长（毫秒）：

SELECT *
FROM goose_settings()
WHERE name = 'progress_bar_time';

将触发进度条显示的最小时长设置为 100 毫秒：

SET
progress_bar_time = 100;

将进度条组件设置为红色文本，并显示当前时间：

.progress_bar --add "{align:right}{min_size:20}{color:red}Time: {sql:select (current_time::varchar).split('.')[1]}{color:reset} "

.progress_bar --add 为叠加式命令，多次调用 --add 会在进度条上叠加更多组件。

将进度条组件设置为蓝色文本，并显示文件缓存 RAM 占用：

.progress_bar --add "{align:right}{min_size:20}{color:blue}External Cache Usage: {sql:select format_bytes(memory_usage_bytes) from goose_memory() where tag='EXTERNAL_FILE_CACHE'}{color:reset};

重置全部现有进度条组件：

.progress_bar --clear

语法高亮器

Goose CLI 客户端包含两个语法高亮器：一个用于 SQL 查询，另一个用于 duckbox 格式结果表。

配置查询语法高亮器

shell 默认启用语法高亮支持。 CLI 的语法高亮器可通过以下命令进行配置。

关闭高亮：

.highlight off

开启高亮：

.highlight on

配置常量高亮颜色：

.constant [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.constantcode
⟨terminal_code
⟩

例如：

.constantcode 033[31m

配置关键字高亮颜色：

.keyword [red|green|yellow|blue|magenta|cyan|white|brightblack|brightred|brightgreen|brightyellow|brightblue|brightmagenta|brightcyan|brightwhite]

.keywordcode
⟨terminal_code
⟩

例如：

.keywordcode 033[31m

配置结果语法高亮器

默认情况下，结果高亮会做以下小幅调整：

• 列名加粗。
• NULL 值显示为灰色。
• 布局元素显示为灰色。

每个组件的高亮都可通过 .highlight_colors 命令自定义。 例如：

.highlight_colors layout red
.highlight_colors column_type yellow
.highlight_colors column_name yellow bold_underline
.highlight_colors numeric_value cyan underline
.highlight_colors temporal_value red bold
.highlight_colors string_value green bold
.highlight_colors footer gray

可通过 .highlight_results off 关闭结果高亮。

缩写

Goose CLI 支持 dot 命令缩写。 当一段字符能唯一匹配某个 dot 命令或参数时，CLI 会自动（静默）补全。 例如：

.mo ma

等价于：

.mode markdown

提示：在 SQL 脚本中建议避免缩写，以提升可读性并确保脚本更具前向兼容性。

从 CSV 导入数据

已弃用：该功能仅为兼容性保留，未来可能移除。 请使用 read_csv 函数或 COPY 语句加载 CSV 文件。

Goose 支持使用 SQL 语法直接查询或导入 CSV 文件， 但也可以按需使用 CLI 专用命令导入 CSV。.import 命令接收两个参数并支持若干选项： 第一个参数是 CSV 文件路径，第二个参数是要创建的 Goose 表名。 由于 Goose（其 CLI 基于 SQLite CLI）类型要求比 SQLite 更严格， 在使用 .import 前必须先创建目标表。若要自动探测 schema 并基于 CSV 建表， 请参阅导入文档中的 read_csv 示例。

在本示例中，先切换到 CSV 模式并设置输出文件路径，以生成 CSV 文件：

.mode csv
.output import_example.csv
SELECT 1 AS col_1, 2 AS col_2
UNION ALL
SELECT 10 AS col1, 20 AS col_2;

CSV 写出后，即可按所需 schema 创建表并导入 CSV。 为避免继续写入上方指定的输出文件，需要将输出重置回终端。 --skip N 用于跳过第一行数据，因为该行是表头，且表已按正确列名创建。

.mode csv
.output
CREATE TABLE test_table
(
    col_1 INTEGER,
    col_2 INTEGER
);
.import import_example.csv test_table --skip 1

注意，.import 会依据当前 .mode 和 .separator 设置识别待导入数据结构。 可通过 --csv 选项覆盖该行为。

.import import_example.csv test_table --skip 1 --csv