QuestDB 10.0.1 常用命令与 API 详解

QuestDB 10.0.1 常用命令与 API 详解：questdb.sh 进程管理、REST API（/ping /exec /imp /write）、ILP TCP/HTTP 写入、PG wire 连接与 systemd 运维命令，全部为实测输出

QuestDBQuestDB命令行运维时间序列OLAP时序NoSQL2026/10/03

QuestDB 10.0.1 常用命令与 API 详解

目标：整理 QuestDB 10.0.1 日常运维与开发接入的完整命令速查：questdb.sh 进程管理、REST API（/ping、/exec、/imp、/write）、ILP（TCP/HTTP）写入、PostgreSQL wire 连接与 systemd 服务命令。文中命令与回显均来自 QuestDB 10.0.1 真实环境实测。

环境信息

  • QuestDB 版本：10.0.1
  • 安装目录：/opt/questdb/bin（questdb.sh、java、questdb.jar）
  • 数据目录：/var/lib/questdb
  • 服务端口：9000（HTTP/REST/ILP over HTTP）、9009（ILP TCP）、8812（PG wire）
  • 默认账号：admin / quest
  • 服务单元：questdb.service（systemd）

工具概览

工具用途载体
questdb.sh进程启停与状态管理服务器本地脚本
curlREST API 与 ILP over HTTP 调用任意客户端
psql / PG 驱动PostgreSQL wire 协议接入任意客户端
ncILP TCP 写入服务器本地
systemctlsystemd 服务管理服务器本地

前置条件

  • 已按安装指南完成部署并处于运行状态
  • REST 调用需知道账号密码（默认 admin/quest）；PG wire 默认数据库名 qdb

1. questdb.sh 进程管理命令

questdb.sh 位于 /opt/questdb/bin/，子命令为 start|status|stop|profile。

1.1 启动

执行命令：

sudo -u questdb /opt/questdb/bin/questdb.sh start -d /var/lib/questdb

执行结果：

Starting QuestDB v10.0.1

💡 说明：-d 指定数据目录。启动后进程立即转入后台，日志输出到数据目录 log/。

1.2 查看状态

执行命令：

sudo -u questdb /opt/questdb/bin/questdb.sh status -d /var/lib/questdb

执行结果：

PID: 71

💡 说明：输出 PID: <进程号> 表示运行中；输出 not running 表示已停止。

1.3 停止

执行命令：

sudo -u questdb /opt/questdb/bin/questdb.sh stop -d /var/lib/questdb

执行结果：

Stopping QuestDB v10.0.1

💡 说明：stop 向进程发送优雅停止信号，等待写入合并完成后退出，避免数据丢失。强杀场景才使用 kill -9 <PID>。

1.4 查看进程与启动参数

执行命令：

ps aux | grep questdb

执行结果：

questdb    71 11.6  2.4 44069732 788524 ?  Sl  09:57  0:29 /opt/questdb/bin/java -DQuestDB-Runtime-66535 -Dcontainerized=false -Dquestdb.libs.dir=/opt/questdb/lib -ea -Dnoebug -XX:ErrorFile=/var/lib/questdb/db/hs_err_pid+%p.log -XX:+UnlockExperimentalVMOptions -XX:+AlwaysPreTouch -XX:+UseParallelGC --sun-misc-unsafe-memory-access=allow --enable-native-access=io.questdb --add-opens=java.base/java.lang=io.questdb --add-opens=java.base/java.lang.reflect=io.questdb --add-opens=java.base/java.nio=io.questdb --add-opens=java.base/java.time.zone=io.questdb --add-exports=java.base/jdk.internal.vm=io.questdb -p /opt/questdb/bin/questdb.jar -m io.questdb/io.questdb.ServerMain -d /var/lib/questdb

💡 说明：实际进程由 questdb.sh 以 -p questdb.jar -m io.questdb/io.questdb.ServerMain（jlink 模块）方式启动。

2. REST API 命令

REST 端点统一在 9000 端口。除 /ping 外均需认证（Authorization: Basic，账号 admin）。

2.1 健康检查 GET /ping

执行命令：

curl -s -o /dev/null -w "%{http_code}" http://localhost:9000/ping

执行结果：

204

💡 说明：HTTP 204 即健康。用于探活脚本与负载均衡检查。

2.2 SQL 查询 GET /exec?query=

/exec 仅支持 GET，参数 query 为 URL 编码后的 SQL。

执行命令：

curl -s "http://localhost:9000/exec?query=select%20version()"
curl -s "http://localhost:9000/exec?query=show%20tables"
curl -s "http://localhost:9000/exec?query=create%20table%20t1%20(ts%20timestamp,%20val%20double)"
curl -s "http://localhost:9000/exec?query=insert%20into%20t1%20values(now(),%201.5)"

执行结果：

{"query":"select version()","columns":[{"name":"version()","type":"STRING"}],"timestamp":-1,"dataset":[["PostgreSQL 12.3, compiled by Visual C++ build 1914, 64-bit, QuestDB"]],"count":1}
{"query":"show tables","columns":[{"name":"table_name","type":"STRING"}],"timestamp":-1,"dataset":[["t1"]],"count":1}
{"ddl":"OK"}
{"dml":"OK"}

💡 说明：返回 JSON 中 columns 为列元数据（名称与类型），dataset 为二维数组，count 为行数，timestamp 为结果集时间戳列索引（-1 表示无）。select version() 返回 PG 兼容层标识字符串。

2.3 CSV 批量导入 POST /imp?tableName=&timestamp=

将 CSV 一次性导入指定表（自动建表），适用于批量历史数据灌入。

执行命令：

curl -s -X POST "http://localhost:9000/imp?tableName=csv_test&timestamp=ts&partitionBy=DAY" \
  -H "Content-Type: text/csv" \
  --data-binary @/var/lib/questdb/import/data.csv

执行结果：

{"status":"OK","location":"/imp?tableName=csv_test&timestamp=ts&partitionBy=DAY","rowsImported":1000,"columns":{"ts":"TIMESTAMP","val":"DOUBLE"},"rowsRejected":0,"errors":null}

💡 说明：tableName 为表名，timestamp 指定 CSV 中时间列列名，partitionBy 指定分区粒度（DAY/WEEK/MONTH/YEAR）。rowsImported 为成功行数，rowsRejected 为拒绝行数。

2.4 ILP over HTTP POST /write

ILP 行通过 HTTP 写入 9000 端口的 /write，返回 204 表示成功。

执行命令：

curl -s -X POST "http://localhost:9000/write" --data-binary $"sensor temp=22.5,city=\"beijing\" $(date +%s%N)\n"

执行结果：

（HTTP 204，无响应体）

💡 说明：ILP 行格式 表名 字段=值,... 时间戳；字段逗号分隔，字符串值加双引号，时间戳为裸纳秒数。批量写入时一次请求可含多行（每行以 \n 结尾）。

3. ILP 协议写入命令（TCP 9009）

ILP TCP 端口 9009 支持直接 socket 写入，常用于 Java/Go 等语言的高吞吐接入。

3.1 单行写入

执行命令：

printf "ilp_test temp=21.5,city=\"shanghai\" %s\n" "$(date +%s%N)" | nc -q1 127.0.0.1 9009
curl -s "http://localhost:9000/exec?query=select%20*%20from%20ilp_test"

执行结果：

{"query":"select * from ilp_test","columns":[{"name":"temp","type":"DOUBLE"},{"name":"city","type":"VARCHAR"},{"name":"timestamp","type":"TIMESTAMP"}],"timestamp":2,"dataset":[[21.5,"shanghai","2026-10-03T09:59:05.668057Z"]],"count":1}

3.2 多行批量写入

执行命令：

printf "m1 temp=1.1,city=\"a\" %s\nm2 temp=2.2,city=\"b\" %s\n" "$(date +%s%N)" "$(date +%s%N)" | nc -q1 127.0.0.1 9009

执行结果：

（无输出，写入成功；随后查询可见两行）

💡 说明：ILP TCP 保持长连接时吞吐最高（官方 ILP 客户端默认复用连接）。nc -q1 发送后等待 1 秒关闭连接。

4. PostgreSQL wire 连接命令（8812）

QuestDB 暴露 PG wire 协议，标准 psql 与 JDBC/psycopg2 等驱动可直接接入。默认数据库名 qdb。

4.1 psql 连接

执行命令：

PGPASSWORD=quest psql -h 127.0.0.1 -p 8812 -U admin -d qdb -c "select version()"

执行结果：

                              version()
---------------------------------------------------------------------
 PostgreSQL 12.3, compiled by Visual C++ build 1914, 64-bit, QuestDB
(1 行记录)

4.2 建表、插入、查询

执行命令：

PGPASSWORD=quest psql -h 127.0.0.1 -p 8812 -U admin -d qdb -c "create table pg_t(ts timestamp, val double)"
PGPASSWORD=quest psql -h 127.0.0.1 -p 8812 -U admin -d qdb -c "insert into pg_t values(now(), 9.99)"
PGPASSWORD=quest psql -h 127.0.0.1 -p 8812 -U admin -d qdb -c "select * from pg_t"

执行结果：

OK
INSERT 0 1
             ts             | val
----------------------------+------
 2026-10-03 09:59:34.560796 | 9.99
(1 行记录)

💡 说明：QuestDB 的 PG 协议支持常见 DDL/DML 与时间序列函数（now()、sum、savg、timeseries 等），也支持预编译语句。连接串示例：postgresql://admin:quest@127.0.0.1:8812/qdb。

5. systemd 运维命令

systemd 部署下（见安装指南）使用标准 systemctl 管理。

执行命令：

systemctl status questdb --no-pager
systemctl restart questdb
systemctl stop questdb
systemctl start questdb
systemctl enable questdb
journalctl -u questdb -n 50

执行结果（status）：

● questdb.service - QuestDB database server
     Loaded: loaded (/etc/systemd/system/questdb.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-03 09:57:10 UTC; 13s ago
    Process: 45 ExecStart=/opt/questdb/bin/questdb.sh start -d /var/lib/questdb (code=exited, status=0/SUCCESS)
   Main PID: 71 (java)

💡 说明：journalctl -u questdb 输出与数据目录 log/questdb-rolling.log.<日期> 一致；排查启动失败优先看这两处日志。

注意事项

  • /exec 仅支持 GET，POST /exec 会返回 Method POST not supported。
  • ILP 字符串字段值必须加双引号（如 city="beijing"），裸字符串会报 field value is invalid。
  • ILP 时间戳单位默认纳秒（line.tcp.timestamp=n），毫秒时间戳会被误解析为 1970 年。
  • REST 除 /ping 外均要求认证；不带认证调用返回 401。
  • 备份数据：直接打包 /var/lib/questdb/db 目录；恢复时将 db 目录原样放回并重启。

常见问题

Q1. curl 调用 /exec 返回 401

  • 现象：Unauthorized，请求被拒。
  • 解决：加认证头 curl -u admin:quest "http://localhost:9000/exec?query=..."。

Q2. ILP 报 INVALID_FIELD_SEPARATOR

  • 现象：写入被拒，错误 INVALID_FIELD_SEPARATOR。
  • 定位：QuestDB 10 ILP 字段以逗号分隔，而非空格。
  • 解决：改为 temp=21.5,city="shanghai" <ts> 格式。

Q3. 大批量导入用 /imp 还是 /write

  • 建议：历史全量数据用 /imp（CSV 直导，一次建表 + 分区）；实时增量用 /write（ILP，低延迟高吞吐）。

Q4. psql 提示 password authentication failed

  • 现象：默认密码错误。
  • 解决：用 PGPASSWORD=quest；或按配置文档修改 pg.password 后重启。

参考链接