编程 Harlequin:终端里的 SQL IDE,配套 hsql 给脚本和 agent 用

2026-11-18 21:31:47

Harlequin:终端里的 SQL IDE,配套 hsql 给脚本和 agent 用

Harlequin 是一个跑在终端里的 SQL IDE。默认体验是 DuckDB:不带参数启动就是一个内存库。Postgres、MySQL/MariaDB、SQLite 等通过适配器接入。同一个包里还带 hsql 命令,用同一批适配器和同一份配置文件,但面向无头场景,适合塞进脚本或交给 agent 调用。

安装

Harlequin 是 Python 程序,要求 Python 3.9+。推荐用 uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install harlequin

uv tool 会把它装进隔离环境并加入 PATH,不污染项目自己的 venv。其它安装方式有 pip install harlequin、pipx,以及 brew install harlequin——brew 的 formula 由社区维护,打包了 Postgres、MySQL/MariaDB、ODBC 适配器及其依赖,安装包更大,换来的是这几个适配器不用再单独装。

适配器

适配器是独立的 Python 包,必须和 Harlequin 装进同一个环境,否则连不上对应数据库。部分适配器提供了 extra:

uv tool install 'harlequin[postgres]'
uv tool install 'harlequin[postgres,mysql,s3]'

DuckDB 适配器随 Harlequin 自带,包含完整的进程内 DuckDB;SQLite3 也自带,用 --adapter sqlite 指定即可,不需要额外装包。

连接与运行

命令形式是 harlequin [OPTIONS] [CONN_STR]。

DuckDB 可以不传任何参数直接进内存库,也可以把文件路径当位置参数传进去,支持多个:

harlequin
harlequin "path/to/duck.db" "another_duck.db"

路径对应的文件不存在会被创建。SQLite 需要显式指定适配器:

harlequin --adapter sqlite "path/to/sqlite.db"

--adapter 有短别名 -a。不同适配器还带各自的选项,全部列表看 harlequin --help。

选择终端 IDE 还是 GUI,主要看工作方式。终端的好处是 SSH 到远端机器上直接开、不用在窗口之间切换、键盘操作连贯、启动快;代价是结果集展示和复杂编辑不如图形客户端,大结果集滚动也不舒服。键位需要一点适应成本,应用内按 F1 可以看帮助,troubleshooting 文档里讲了键位、外观和复制粘贴的问题。日常写查询、巡检、临时看数据,终端足够了;要做表结构可视化或大量手工编辑,GUI 更省力。

配置

主题、键位、远程/本地文件显示、数字格式化的 locale 等都能在命令行传,但更适合写进 profile 文件。配置文件路径和字段见文档的 config-file 一节。

profile 里的字符串值可以引用环境变量:

password = "${MYPASSWORD}"

也支持带默认值的写法,例如 ${MYHOST:-localhost}。这样一来,团队共享的配置文件里就不含明文凭据,每个人在自己环境里导出变量即可。适配器声明为 secret 的字段,Harlequin 在打印时会被掩码。

hsql 读的是同一份配置文件,并且提供三条自检命令:hsql --config show、hsql --config validate、hsql --config schema,分别用来展示当前生效配置、校验配置合法性、输出配置的 schema。

用 hsql 接脚本和 agent

hsql 随 Harlequin 一起打包,不需要额外安装。指定 profile 执行一条 SQL:

hsql -P dev -c "select * from users"

输出是 id | name 这样的文本表格,直接可以进管道,也可以作为 agent 的观察结果。

不写 SQL 也能探索 catalog:

hsql --catalog --path mydb.analytics          # 列出该 schema 下的关系
hsql --catalog --path mydb.analytics.orders   # 列出该表的字段
hsql --catalog-search customer_id             # 在所有层级里搜这个名字

比起直接开 mysql 或 psql 客户端,hsql 的收益是统一:一套适配器、一份配置文件,IDE 和 CLI 都生效,跨数据库的命令形式一致;catalog 探索不用记各家的 information_schema 写法;输出是稳定的文本表格,适合程序消费。代价是多一层 Python 环境和适配器安装,而且下面这些限制要清楚。

限制权限:

hsql --read-only
hsql --timeout 30

--read-only 是以数据库拒绝写入的模式连接,前提是适配器能把只读强制到数据库侧;如果适配器无法强制执行,Harlequin 会拒绝启动,而不是退化成客户端层面的拦截。所以能不能用 --read-only 顶事,取决于你用的适配器。--timeout 30 是取消超过 30 秒的运行,不要把它当成数据库的 statement timeout 来依赖——它是客户端侧中止,服务端是否真的停下、长事务的资源是否释放,要按具体数据库和适配器的行为确认。这两项同时也是 profile 的键,可以写进配置文件省得每次敲。Harlequin 本身也支持 --read-only。

Django

django-harlequin 提供一个 management command,拿 Django 的数据库配置直接启动 Harlequin:

./manage.py harlequin

省掉手写连接串这一步。

其它

应用内按 F1 看帮助;键位、外观、复制粘贴的问题在 troubleshooting 文档里;提问走 GitHub Discussions,报 bug 走 Issues。

复制全文 生成海报 MySQL SQLite DuckDB 命令行工具

推荐文章

程序员茄子在线接单