sqlstore

gitee.com/idcu-go/sqlstore

当前版本：v0.1.0

1. 定位 + 当前版本

模块类型：通用公共模块（极简「时序样本」存储抽象 + 默认本地 SQLite 落盘）。

提供「按目标 + 时间窗写入 / 查询结构化样本」的存储抽象 Store 与默认的本地 SQLiteStore 实现，把监控领域反复出现的「历史样本落盘 / 回溯」抽成通用能力， 同时让后端可替换：默认用现代 doc(modernc.org/sqlite，无 cgo) 落本地文件；需要 对接远端时序库(ClickHouse / Loki / InfluxDB 等)时，实现 Store 接口并替换注入点即可， 上层(写入 / 查询) 不感知。本包不依赖任何 idcu-go 领域/应用类型，只依赖数据库驱动。

2. 安装

go get gitee.com/idcu-go/sqlstore@v0.1.0

依赖：

• 内部（gitee.com/idcu-go/*）：无
• 外部（第三方）：modernc.org/sqlite（无 cgo 的 SQLite 驱动）

3. API 签名

// 时序样本（存储无关）
type Sample struct {
	Name   string  `json:"name"`   // 序列/目标名
	Host   string  `json:"host"`
	Ts     int64   `json:"ts"`     // Unix 毫秒
	OK     bool    `json:"ok"`
	RTTMs  float64 `json:"rtt_ms"` // 毫秒
	Loss   float64 `json:"loss"`   // [0,1]
	Status string  `json:"status"` // up/down
}

// 存储抽象：实现者只需满足本接口
type Store interface {
	Insert(s Sample) error
	Query(name string, since, until int64, limit int) ([]Sample, error)
	Close() error
}

// 默认 SQLite 实现
func NewSQLiteStore(path string) (*SQLiteStore, error)

4. 关键类型/结构体

5. 最小用法示例

package main

import (
	"fmt"

	"gitee.com/idcu-go/sqlstore"
)

func main() {
	st, err := sqlstore.NewSQLiteStore("./hist.db")
	if err != nil {
		panic(err)
	}
	defer st.Close()

	_ = st.Insert(sqlstore.Sample{Name: "svc-a", Host: "h1",
		Ts: 1700000000000, OK: true, RTTMs: 3.2, Status: "up"})

	rows, _ := st.Query("svc-a", 0, 0, 100)
	for _, s := range rows {
		fmt.Printf("%s %d ok=%v rtt=%.1fms\n", s.Name, s.Ts, s.OK, s.RTTMs)
	}
}

6. 工作机制/边界语义

• 存储无关：Sample / Store 不绑定任何领域类型，上层负责把「领域样本」转换为 Sample（如 realtime-ping 的 monitor.Sample → sqlstore.Sample）。
• 默认落盘：SQLiteStore 基于现代 doc(无 cgo) 打开本地文件并自动建表(samples)； Insert 在调用方 goroutine 同步执行，SetMaxOpenConns(1) 保证单写者无并发写锁。
• 查询语义：Query 按 name 过滤(name=="" 查全部)，[since, until] 时间窗含边界 (0 表示该侧不设界)，limit<=0 用 DefaultLimit，结果按 id 倒序（最新在前）。
• 可替换：接远端时序库时实现 Store 并替换注入点，调用方零改动。

7. 适用场景

• 监控历史样本落盘与回溯查询（探测结果的「可回溯」分析）。
• 需要本地持久化时序样本、又不想引入重型时序库的应用。
• 作为后续对接远端时序库(ClickHouse / Loki / InfluxDB)的统一接缝层。

8. 变更记录

见仓库 tag v0.1.0（gitee.com/idcu-go/sqlstore 对应提交）。后续版本变更以 git tag / CHANGELOG 为准。