product / what's inside

TSDB 核心能力

本页介绍 TSDB 的三项核心能力：分布式事务控制面、在线恢复，以及流式处理与 SDK 接入。每一项均配有测试、故障演练或 benchmark 数据，详见下文。

事务 distributed control plane

恢复 online recovery

接入 stream + sdk

核心能力性能数据返回首页

distributed transactions

分布式事务控制面

控制面负责协调、提交与重放。相关逻辑在 benchmark、故障演练与恢复流程中被持续执行，而非仅作为静态代码存在。

distributed control plane

Leader Lease + Metadata Quorum + 2PC

leader lease 决定每个分片的写入归属，metadata quorum 记录事务投票， 2PC 推进跨分片提交，decision replay 负责收尾及故障后的状态对齐。

01. lease 决定分片的写入归属
02. 2PC 保证跨分片 prepare / commit 的原子性
03. replay 在节点重启或局部故障后补齐事务状态

该机制的实际效果：分布式写入可协调、可重放、可恢复，避免多节点各自写入导致的状态不一致。

STATE 01  PREPARE  -> lease owner validates shard intent
STATE 02  QUORUM   -> metadata quorum records transaction vote
STATE 03  COMMIT   -> two-phase commit advances all participants
STATE 04  REPLAY   -> recovering nodes reconcile final decision

$ tsdb-admin txn verify --mode strict --shard 0x09ff2

online recovery

在线恢复与副本修复

恢复逻辑与写路径、控制面共用同一套代码，纳入日常回归。节点宕机重启后，系统通过 repair 机制补齐副本数据。

recovery state

Telemetry

Recovery State

通过 `/cluster/recovery/state` 查询各分片的修复进度。

Exercise

Chaos Evidence

恢复能力由自动化故障演练验证：终止节点进程，校验恢复结果。

repair trace

[t29] online recovery convergence = 34ms
[t30] repair + state stabilization = 2072ms
[state] periodic leader repair = enabled
[api] /cluster/recovery/state = observable

online recovery + repair

恢复进度与修复耗时均可观测

副本修复由 leader 周期性触发，恢复进度通过状态接口暴露， t29 / t30 两组耗时指标随每次回归更新。

01. 状态接口暴露恢复阶段与收敛进度
02. leader 周期性触发 repair，该路径由故障演练覆盖
03. t29 / t30 耗时数据随每次回归重新测量

stream + sdk

Stream HA 与开发者接入

流式订阅与 SDK 是外部使用该系统的主要入口，均配有独立的功能测试。

stream ha + client access

Stream HA 与多语言客户端

流写入依赖 sequence 与 replay buffer：连接断开重连后，缺失数据会重新推送；当请求到达非 owner 节点时，会被转发至正确节点。提供 Python、JDBC、REST 三种客户端，并支持 Rust crate 与 C / C++ 协议级接入。

01. 重连后通过 replay 补齐缺失数据，非 owner 请求自动转发
02. Python 端提供 `TsdbClient`、`read_db()`、`to_db()`
03. JDBC 支持查询与元数据读取

developer surface

from tsdb import TsdbClient, read_db

client = TsdbClient("http://127.0.0.1:8080")
client.health()

frame = read_db(
    "SELECT * FROM trades LIMIT 10",
    url="http://127.0.0.1:8080",
)

jdbc:tsdb://127.0.0.1:8080

以上为 Python 与 JDBC 的最小接入示例，更多用法见仓库 python/ 与 jdbc/ 目录。

benchmark

主要性能指标

vs DolphinDB · 内存口径

`order_by_limit 71.40×`（1.0 vs 71.4ms）
`window_rownum 22.20×` · `asof_join 17.67×`
`range_scan 2.61×` · `group_by 110×`
`group_by / point` 亚毫秒领先
8/8 rows_match 全胜或平（2026-08-27 复测）

vs DolphinDB · DFS 口径

`order_by_limit ≈45×`（1.0 vs 44.6ms）
`time_bucket ≈44×` · `asof_join ≈16×`
`point_query ≈11×` · `window ≈11×` · `group_by 5×`
`range_scan 1.00×`（历史失分点已追平）
落盘体积约为 DDB 最优压缩的 1/16

vs PostgreSQL · tcp-fast

`q1–q9 全胜`（二进制通道）
`q7 lastpoint 915×`（0.02 vs 18.3ms）
`q9 group-by 710×` · `q5 聚合 567×`
`q1 点查 13×` · `q4 13.6×` · `q3 11×`
点查热路径 p50 0.013ms

Client Surface

`tcp-mpx 单连接 8 线程 14,298 ops/s`
`PREPARE 预编译重查询再 −24%`
`python / go / c++ 三端 SDK`
`rust = 嵌入库 Tsdb::open`（进程内直调）
`五监听器可启停 · 纯二进制节点`

以上为 2026-08-25 冻结构建的同机对打结果（432 万行，rows_match 三口径门禁全绿；1206 单元测试通过）。完整报告见仓库 bench/ 与 docs/ 目录。

usage

接入方式：启动服务 -> Python、JDBC、Rust 、C 、C++

server boot

1. 启动服务

cargo build --release --bin tsdb-server
./target/release/tsdb-server \
  --addr 127.0.0.1:8080 \
  --data-dir ./data

python sdk

2. 使用 Python

from tsdb import TsdbClient, read_db

client = TsdbClient("http://127.0.0.1:8080")
print(client.health())

frame = read_db(
    "SELECT * FROM trades LIMIT 10",
    url="http://127.0.0.1:8080",
)

jdbc access

3. 使用 JDBC

Connection conn =
    DriverManager.getConnection(
        "jdbc:tsdb://127.0.0.1:8080");

Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery(
    "SELECT * FROM trades LIMIT 10");

rust crate

4. 使用 Rust

use tsdb::network::client::Client;

#[tokio::main]
async fn main() -> tsdb::Result<()> {
    let client =
        Client::new("http://127.0.0.1:8080");

    client.health_check().await?;
    let result = client
        .execute_query(
            "SELECT * FROM trades LIMIT 10")
        .await?;
    Ok(())
}

c / rest

5. 使用 C

/* 与 tsdb_fdw 相同的方式：
   libcurl POST /jdbc */
CURL *curl = curl_easy_init();
struct curl_slist *h = NULL;
h = curl_slist_append(h,
    "Content-Type: application/json");

curl_easy_setopt(curl, CURLOPT_URL,
    "http://127.0.0.1:8080/jdbc");
curl_easy_setopt(curl,
    CURLOPT_HTTPHEADER, h);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS,
    "{\"action\":\"execute\","
    "\"sql\":\"SELECT * FROM trades"
    " LIMIT 10\"}");

curl_easy_perform(curl);

c++ / rest

6. 使用 C++

// REST 接入；大批量写入可走
// TCP 二进制协议 :9090
CURL *curl = curl_easy_init();
curl_easy_setopt(curl, CURLOPT_URL,
    "http://127.0.0.1:8080/jdbc");

std::string body = R"({
  "action": "execute",
  "sql": "SELECT * FROM trades LIMIT 10"
})";

curl_easy_setopt(curl,
    CURLOPT_POSTFIELDS, body.c_str());
curl_easy_perform(curl);