用户文档

01快速开始

方式一：deb 安装（推荐，Ubuntu 24.04 / Debian 12+）

wget https://db.myagent.pub/dl/tsdb-server_0.2.0-1_amd64.deb
sudo apt install ./tsdb-server_0.2.0-1_amd64.deb
sudo systemctl start tsdb          # 已随包自启用

安装内容：/usr/bin/tsdb-server、/usr/bin/tsdb-cli、配置 /etc/tsdb/tsdb.toml、systemd 单元 tsdb.service、数据目录 /var/lib/tsdb。安装细节见管理员文档。

方式二：源码构建

git clone <repo> && cd tsdb
./scripts/build-linux.sh           # macOS: build-macos.sh；Windows: build-windows.sh --check
./target/release/tsdb-server --addr 127.0.0.1:8080 --data-dir ./data

构建依赖：Rust 1.95.0（仓库已 pin）、cmake、protoc、pkg-config、libhdf5-dev。

第一条查询

curl -X POST http://127.0.0.1:8080/query \
     -H 'Content-Type: application/json' \
     -d '{"query":"CREATE TABLE demo (ts TIMESTAMP, sym STRING, v DOUBLE)"}'
curl -X POST http://127.0.0.1:8080/query \
     -H 'Content-Type: application/json' \
     -d '{"query":"INSERT INTO demo VALUES (1,\'AAPL\',185.5)"}'
curl -X POST http://127.0.0.1:8080/query \
     -H 'Content-Type: application/json' \
     -d '{"query":"SELECT sym, count(*), sum(v) FROM demo GROUP BY sym"}'

02连接与认证

三种模式：未配置凭证即信任模式（本地开发）；配置 auth_token 即静态 token；创建用户后进入用户模式（PG 风格登录 + 双 token 轮换）。所有 protected 端点接受 Authorization: Bearer <token> 或 Basic（用户名/密码）。

PG 风格登录与双 token

# 首次启动引导 admin（仅用户表为空时创建）
tsdb-server --data-dir ./data --admin-user admin --admin-password 'change-me'

# 登录换取 (access, refresh) 双 token
curl -X POST http://127.0.0.1:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"change-me"}'
# → {"access_token":"...","refresh_token":"...","expires_in":900,...}

# access 短 TTL（默认 15 分钟）；过期后用 refresh 轮换（旧 refresh 立即作废，防重放）
curl -X POST http://127.0.0.1:8080/auth/refresh -d '{"refresh_token":"..."}'
# 登出撤销 refresh
curl -X POST http://127.0.0.1:8080/auth/logout  -d '{"refresh_token":"..."}'

签名密钥持久化于 <data_dir>/auth_secret，重启后已签发 token 仍有效；TTL 可配（--access-token-ttl-min / --refresh-token-ttl-days）。Python SDK login() 后遇 401 自动单飞刷新。

用户管理（SQL 与 HTTP 等价）

CREATE USER alice WITH PASSWORD '...' ADMIN;   -- ADMIN 可选
ALTER USER alice PASSWORD 'new-password';       -- 改密即失效旧 token
DROP USER alice;  SHOW USERS;

HTTP（admin）：GET /auth/me · GET /auth/users · POST /auth/users · DELETE /auth/users/{name}。

tsdb-cli（随包附带的命令行）

tsdb-cli --url http://127.0.0.1:8080 health          # 健康检查
tsdb-cli --url http://127.0.0.1:8080 stats           # 服务器统计
tsdb-cli --url http://127.0.0.1:8080 list-tables     # 表清单
tsdb-cli --url http://127.0.0.1:8080 table-info demo # 表结构
tsdb-cli --url http://127.0.0.1:8080 query "SELECT count(*) FROM demo"

TCP 端口认证

配置凭证后四个 TCP 端口同样要求认证（不配置则完全开放）：9090 管理口第一帧 {"cmd":"auth","token":"..."}；9091 订阅行协议 AUTH <token>；9092 tcp-fast / 9093 tcp-mpx 首帧 AUTH + token。

TLS（HTTPS）

同时提供 tls_cert 与 tls_key（PEM）即可启用；二者必须成对出现。

03SQL 参考

支持标准 SQL（DDL/DML/CTE/递归）之上的时序扩展。完整语法见仓库 README「SQL 参考」。

数据类型

TIMESTAMP / DATE / TIME / BOOLEAN / INT8-64 / FLOAT32/64 / DOUBLE / STRING / SYMBOL / DECIMAL / UUID / BLOB / DURATION / VECTOR / ARRAYVECTOR。

04多协议接入

传输层选择建议

• 延迟敏感点查 → tcp-fast（Python FastQueryClient；§8.24 实测 tcp-fast 通道下 q1–q9 全部反超 PostgreSQL）
• 单连接多线程 / 重查询复用 → tcp-mpx（PREPARE 预编译再省 ~24%）
• 批量读写 → Arrow（query_arrow / insert_df_arrow，708k rows/s）
• 一般查询 → HTTP + 连接池预热 client.warmup()

tcp-mpx 快速示例（Python）

from tsdb.mpx_client import MpxClient

m = MpxClient("http://127.0.0.1:8080", token="<token>")
rows = m.query("SELECT count(*) FROM demo")            # 单连接线程安全

with m.prepare("SELECT sym, sum(v) FROM demo GROUP BY sym") as p:
    p.execute(); p.execute()                            # 预编译复用（免重复解析）

with m.prepare("SELECT v FROM demo WHERE sym = ? LIMIT 1") as p:
    p.execute(["AAPL"])                                 # 带 ? 参数

# 或整客户端切换通道（仅影响 SELECT）
from tsdb.client import TsdbClient
c = TsdbClient("http://127.0.0.1:8080", protocol="mpx")  # "http"/"fast"/"mpx"

Go：gotsdb.NewMpx / Prepare / Execute；C++：tsdb::MpxClient（header-only，见仓库 go-tsdb / cpp-tsdb）。帧格式与语义详见仓库文档 §8.35。

05流式订阅

9091 行协议：连接后发送 SUB <table>，服务端回 OK，此后每个 INSERT 批次推送一行 JSON（{"table":...,"rows":[[..]]}）；PING→PONG；一连接一订阅，断连即退订。

Python

from tsdb.client import TsdbClient
c = TsdbClient(url, token=token)
for batch in c.subscribe("demo"):        # 同步生成器
    print(batch["rows"])

# asyncio
from tsdb.async_client import AsyncTsdbClient
ac = AsyncTsdbClient(url, token=token)
async for batch in ac.subscribe("demo"): ...

Go：client.Subscribe(ctx, table) 返回 channel；C++：client.subscribe(table, on_batch)（回调返回 false 退订）。

06导入导出

端点 POST /import / POST /export；路径相对服务端 <data_dir>/io（沙箱约束）。支持 CSV / Parquet / HDF5 / Feather / Stata / Pickle 等 7 种格式。

curl -X POST http://127.0.0.1:8080/import \
     -H 'Content-Type: application/json' \
     -d '{"table_name":"demo","format":"Csv","path":"demo.csv"}'
curl -X POST http://127.0.0.1:8080/export \
     -H 'Content-Type: application/json' \
     -d '{"table_name":"demo","format":"Parquet","file_path":"out.parquet"}'

07Python SDK

from tsdb.client import TsdbClient
c = TsdbClient("http://127.0.0.1:8080", token="...", retries=3)
c.warmup()                                   # 预热连接池（首查 0.85→0.67ms）
df = c.query_arrow("SELECT * FROM demo").to_pandas()
c.insert_df_arrow("demo", df)                # 708k rows/s
c.insert_rows("demo", rows, batch_size=2000) # 分块 SQL 批量

08JDBC 与生态

09Console 命令

进程内管理台（console 二进制，直开本地数据目录，与 server 同 data_dir 不可同时运行）：交互式 / 命令行 / JSON 输出三种用法。六类命令：

• 系统信息：status / version / config
• 会话管理：sessions / kill
• 数据库操作：tables / schema / optimize
• 性能监控：metrics / slow-queries
• 权限管理：users / roles / grants
• 数据操作：export / import / checkpoint

完整参考见仓库 docs/console_commands.md。

10FAQ

单行写入很慢？

持久模式（every-write）下单行 INSERT 独立 WAL 同步，~228–777 rows/s 是语义地板（§8.20）。请改批量：insert_rows / insert_df_arrow（9 万–70 万 rows/s）。

重复查询结果没变？

结果缓存默认 TTL 5000ms（TSDB_RESULT_CACHE_TTL_MS）。开发期可设 0 关闭；HTTP 与 tcp 二进制通道共享该缓存（§8.32 修齐）。

8080 被占用装完启动失败？

改 /etc/tsdb/tsdb.toml 的 addr（conffile，改完 systemctl restart tsdb）——实机验证过（§8.38）。协议端口也可独立覆盖，见 端口矩阵。

PREPARE 支持哪些语句？

仅 SELECT（安全边界，非 SELECT 会被拒绝）。带 ? 参数的执行走安全字面量渲染（会重新解析）；无参执行走缓存 AST 直执行（免解析，重查询再省 ~24%）。

能不能不起服务、进程内直接用？

可以。Rust 侧 Tsdb::open(config) 嵌入模式零网络开销直调引擎（db.execute_query(...)）；data_dir: ":memory:" 即纯内存库。运行中可 start_server() 升级为服务模式、stop_server() 降级回来（引擎与数据不变）。cargo build --no-default-features 可裁掉整个网络栈做纯嵌入构建，示例见仓库 examples/embedded_and_server.rs。