# sqlstore

**Repository Path**: idcu-go/sqlstore

## Basic Information

- **Project Name**: sqlstore
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# gitee.com/idcu-go/sqlstore

> 当前版本：**v0.1.0**
## 1. 定位 + 当前版本
> 模块类型：**通用公共模块 · 基础 infra**（极简「时序样本」存储抽象 + 默认本地 SQLite 落盘）。

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

## 2. 安装

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

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

## 3. API 签名

```go
// 时序样本（存储无关）
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. 关键类型/结构体

| 类型 | 字段 | 说明 |
|---|---|---|
| `Sample` | `Name`/`Host`/`Ts`/`OK`/`RTTMs`/`Loss`/`Status` | 存储无关的时序样本最小集 |
| `Store` | — | 存储抽象接口（Insert/Query/Close） |
| `SQLiteStore` | `db *sql.DB` | 默认本地 SQLite 实现（单写者，`SetMaxOpenConns(1)`） |
| `DefaultLimit` | — | `Query` 在 `limit<=0` 时的默认返回条数（1000） |

## 5. 最小用法示例

```go
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`（如 `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 为准。