跳到主要内容

命令行客户端

Goose 命令行客户端当前最新稳定版本为 Galileo。

安装​

Goose CLI（命令行界面）是一个无依赖的单一可执行文件。Windows、Mac 和 Linux 均提供预编译版本，包含稳定版与由 GitHub Actions 生成的 nightly 构建。下载链接见安装页面中的 CLI 标签。

Goose CLI 基于 SQLite 命令行 shell，因此其 CLI 专有功能与 SQLite 文档中的描述较为相似（但 Goose 的 SQL 语法总体遵循 PostgreSQL 约定，仅有少量例外）。

快速开始​

下载 CLI 可执行文件后，先解压并保存到任意目录。 在终端进入该目录后，执行 goose 运行可执行文件。 若在 PowerShell 或 POSIX shell 环境中，请改用 ./goose。

用法​

goose 命令的典型用法如下：

goose ⟨OPTIONS⟩ ⟨FILENAME⟩

选项​

⟨OPTIONS⟩ 部分对应 CLI 客户端参数。常见选项包括：

  • -csv：将输出模式设为 CSV
  • -json：将输出模式设为 JSON
  • -readonly：以只读模式打开数据库（参见 Goose 并发）

完整选项列表见命令行参数页面。

内存数据库与持久化数据库​

当未提供 ⟨FILENAME⟩ 参数时，Goose CLI 会打开临时内存数据库。 你会看到 Goose 版本号、连接信息以及以 D 开头的提示符。

goose
Goose vo.6.2 (Galileo)
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D

若要打开或创建持久化数据库，只需将路径作为命令行参数传入：

goose my_database.goose

在 CLI 中执行 SQL 语句​

CLI 启动后，输入以分号结尾的 SQL 语句并回车即可执行，结果会在终端中以表格显示。 若省略分号，回车将进入多行 SQL 输入模式。

SELECT 'quack' AS my_column;
my_column
quack

CLI 支持 Goose 全部丰富的 SQL 语法，包括 SELECT、CREATE、ALTER 等语句。

编辑器功能​

CLI 支持自动补全，并在部分平台提供较完善的编辑功能与语法高亮。

退出 CLI​

若平台支持，可按 Ctrl+D 退出 CLI。否则可按 Ctrl+C 或使用 .exit 命令。 如果使用的是持久化数据库，Goose 会自动执行 checkpoint（将最新修改写回磁盘）并关闭连接。 这会移除 .wal 文件（即 write-ahead log），并将数据整合回单文件数据库。

Dot 命令​

除 SQL 语法外，CLI 还支持输入特殊的 dot 命令。 使用时以句点（.）开头，后面紧跟要执行的命令名。命令附加参数写在后方并以空格分隔。 若参数包含空格，可用单引号或双引号包裹。dot 命令必须写在单行内，且句点前不能有空白字符。行尾不需要分号。

常用配置可存放在 ~/.gooserc 文件中，CLI 客户端启动时会自动加载。更多信息见下文配置 CLI。

提示：若要阻止 Goose CLI 客户端读取 ~/.gooserc 文件，可按如下方式启动：

goose -init /dev/null

下面简要介绍几个重要 dot 命令。完整列表见 dot commands 页面或使用 .help 命令查看。

打开数据库文件​

除在启动 CLI 时连接数据库外，也可使用 .open 建立新数据库连接。 若不提供额外参数，会创建新的内存数据库连接。CLI 连接关闭后该数据库不会持久化。

.open

.open 命令支持若干可选参数，其中最后一个参数可指定持久化数据库路径（或创建位置）。 也可使用特殊字符串 :memory: 打开临时内存数据库。

.open persistent.goose

警告：.open 会关闭当前数据库。 若要保留当前数据库并新增一个数据库，请使用 ATTACH 语句。

.open 的一个重要选项是 --readonly。启用后将禁止对数据库进行任何修改。 要以只读方式打开，数据库必须已存在。这也意味着新的内存数据库无法以只读方式打开，因为内存数据库是在连接时创建的。

.open --readonly preexisting.goose

输出格式​

.mode dot 命令可用于更改终端输出表格外观。 可选模式包括默认的 duckbox、供其他工具读取的 csv 与 json、用于文档的 markdown 与 latex，以及用于生成 SQL 语句的 insert。

将结果写入文件​

默认情况下，Goose CLI 将结果输出到终端标准输出。你可以通过 .output 或 .once 修改此行为。 详情见 output dot 命令文档。

从文件读取 SQL​

Goose CLI 可通过 .read 从外部文件读取 SQL 命令与 dot 命令，而不是在终端逐条输入。 这让你可以按顺序批量执行命令，也便于保存与复用命令序列。

.read 命令只需一个参数：包含 SQL 和/或命令的文件路径。执行完文件内命令后，控制权会回到终端。 该文件的输出同样受前文 .output 与 .once 控制：可以回显到终端（如下方第一个示例），也可输出到其他文件（如下方第二个示例）。

此示例中，文件 select_example.sql 与 goose.exe 位于同一目录，包含以下 SQL 语句：

SELECT *
FROM generate_series(5);

在 CLI 中执行时使用 .read 命令。

.read select_example.sql

默认情况下，下面的输出会返回到终端。表格格式可通过 .output 或 .once 调整。

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

单次 .read 也可以执行多条命令（包含 SQL 与 dot 命令）。 此示例中，write_markdown_to_file.sql 与 goose.exe 位于同一目录，包含以下命令：

.mode markdown
.output series.mdx
SELECT *
FROM generate_series(5);

执行方式与前文一致，仍使用 .read 命令。

.read write_markdown_to_file.sql

在这个例子中，终端不会收到输出。系统会创建文件 series.mdx（若已存在则覆盖），内容为下方所示的 Markdown 格式结果：

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

配置 CLI​

可使用多个 dot 命令来配置 CLI。 CLI 启动时会读取并执行 ~/.gooserc 中全部命令（包括 dot 命令与 SQL 语句），从而保存 CLI 的配置状态。 你也可以通过 -init 指向其他初始化文件。

设置自定义提示符​

例如，在 Goose CLI 同目录下创建 prompt.sql，可将 Goose 提示符改为鸭头并执行 SQL 语句。 注意鸭头由 Unicode 字符组成，并非在所有终端环境都可正常显示（如 Windows，除非在 WSL + Windows Terminal 下运行）。

.prompt '⚫◗ '

要在初始化时加载该文件，可使用：

goose -init prompt.sql

输出如下：

-- Loading resources from prompt.sql
v⟨version⟩ ⟨git_hash⟩
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
⚫◗

非交互式用法​

若要读取/处理文件并立即退出，可将文件内容重定向到 goose：

goose < select_example.sql

若要直接在命令行传入 SQL 文本执行命令，可为 goose 传入两个参数：数据库位置（或 :memory:）与待执行 SQL 字符串。

goose :memory: "SELECT 42 AS the_answer"

加载扩展​

加载扩展时，和普通 SQL 一样使用 Goose 的 INSTALL 与 LOAD 命令。

INSTALL fts;
LOAD fts;

详情见扩展文档。

从 stdin 读取与写入 stdout​

在 Unix 环境下，在多个命令间通过管道传递数据通常很有用。 Goose 可在 SQL 命令中通过 stdin（/dev/stdin）与 stdout（/dev/stdout）进行读写，因为管道与文件句柄行为非常接近。

以下命令会创建一个示例 CSV：

COPY (SELECT 42 AS woot UNION ALL SELECT 43 AS woot) TO 'test.csv' (HEADER);

首先读取文件并通过管道传给 goose CLI 可执行文件。向 Goose CLI 传入数据库位置（此处为内存数据库）以及一条使用 /dev/stdin 作为文件路径的 SQL 命令。

cat test.csv | goose -c "SELECT * FROM read_csv('/dev/stdin')"
woot
42
43

若要回写到 stdout，可在 COPY 命令中使用 /dev/stdout 文件路径。

cat test.csv | \
    goose -c "COPY (SELECT * FROM read_csv('/dev/stdin')) TO '/dev/stdout' WITH (FORMAT csv, HEADER)"
woot
42
43

读取环境变量​

getenv 函数可用于读取环境变量。

示例​

要从 HOME 环境变量读取用户主目录路径，可使用：

SELECT getenv('HOME') AS home;
home
/Users/user_name

getenv 的输出可用于设置配置项。 例如，要根据环境变量 DEFAULT_NULL_ORDER 设置 NULL 排序，可使用：

SET default_null_order = getenv('DEFAULT_NULL_ORDER');

读取环境变量的限制​

仅当 enable_external_access 选项为 true（默认值）时，getenv 才可执行。 该函数仅在 CLI 客户端中可用，其他 Goose 客户端不支持。

预处理语句​

除常规 SELECT 外，Goose CLI 也支持执行预处理语句。 在 CLI 客户端中创建并执行预处理语句时，使用 PREPARE 子句与 EXECUTE 语句。

查询完成 ETA​

Goose CLI 现可为运行中的查询提供智能剩余时间估算，并在完成时显示总执行时间。

在 Goose CLI 执行查询时，进度条会显示预计剩余完成时间。该功能使用高级统计建模（Kalman filtering），比简单线性外推更准确。

工作原理​

Goose 按以下流程计算预计完成时间：

  1. 进度监控：Goose 内部进度 API 报告正在运行查询的预计完成百分比
  2. 统计滤波：Kalman filter 平滑含噪进度测量并考虑执行波动
  3. 持续修正：系统随新进度数据不断更新预计完成时间，提升全程准确性

Kalman filter 会适配变化中的执行条件，如内存压力、I/O 瓶颈或网络延迟。由于这种自适应特性，预计完成时间不一定线性下降；当查询执行变得更不可预测时，估计值可能上升。

影响查询完成 ETA 准确性的因素​

在以下情况下，完成时间估计可能不够可靠：

系统资源受限：

  • 内存压力导致磁盘换页
  • 竞争进程造成 CPU 负载过高
  • 磁盘 I/O 瓶颈

查询执行特征：

  • 可变执行阶段（初始化与主处理差异明显）
  • 依赖网络且延迟不稳定的操作
  • 分支逻辑不可预测的查询
  • 远程数据源操作
  • 外部函数调用
  • 高度倾斜的数据分布