# fox-tdengine

**Repository Path**: fierce_wolf/fox-tdengine

## Basic Information

- **Project Name**: fox-tdengine
- **Description**: No description available
- **Primary Language**: Go
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-27
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tdengine

TDengine 数据库操作封装包，供多项目复用。

## 特性

- 基于官方 WebSocket 驱动（`github.com/taosdata/driver-go/v3/taosWS`），纯 Go 实现，无需安装本地客户端库
- **连接复用**：程序启动时建立一个 `Client`，后续所有增删改查复用该连接，退出时关闭
- **自动重连**：每次操作前自动检查连接健康状态，连接断开（如数据库重启）时自动重建，对调用方透明
- 数据库 / 超级表 / 子表管理
- 数据增删改查

## 连接生命周期（建议用法）

```go
import "kline/tdengine"

cfg := tdengine.DefaultConfig()
cfg.Host = "192.168.1.3"
cfg.Database = "stock_db"

// 1. 启动时建立唯一连接
client, err := tdengine.New(cfg)
if err != nil {
    panic(err)
}

// 2. 后续所有增删改查复用该连接（断开时自动重连，无需手动处理）
client.CreateStable(...)
client.Insert(...)
client.Query(...)

// 3. 程序退出前关闭连接
defer client.Close()
```

## 连接配置（Config）

| 字段 | 说明 |
| --- | --- |
| `Host` | 服务地址（IP 或域名） |
| `Port` | taosAdapter WebSocket 端口，默认 6041 |
| `User` / `Password` | 账号密码 |
| `Database` | 数据库名；非空时 `New` 自动创建（不存在），并作为连接池的默认库（每条连接自带选库，无需 `USE`） |
| `DBParams` | 可选建库参数（仅首次建库生效），如 `KEEP 10950`、`PRECISION 'ms'` |

## 主要 API

| 类别 | 函数 | 说明 |
| --- | --- | --- |
| 连接 | `New` / `Connect` / `Close` / `Ping` | 建立 / 关闭连接、探活（异常时自动重连） |
| 数据库 | `CreateDatabase` / `DropDatabase` | 建库 / 删库 |
| 超级表 | `CreateStable` / `DropStable` | 建 / 删超级表 |
| 子表 | `CreateChildTable` / `DropChildTable` / `ChildTableExists` / `ListChildTables` | 子表管理 |
| 数据 | `Insert` / `Delete` / `UpdateTag` | 增 / 删 / 改 tag |
| 查询 | `Query` / `QueryRow` / `QueryMaps` | 查询结果集 / 单行 / map 列表 |

## 使用示例

```go
// 建超级表（幂等）
client.CreateStable("kline",
    []string{"ts TIMESTAMP", "close DOUBLE"},
    []string{"code NCHAR(16)", "name NCHAR(64)"})

// 建子表（幂等）
client.CreateChildTable("kline_600519", "kline", "600519", "贵州茅台")

// 批量插入
client.Insert("kline_600519",
    []string{"ts", "close"},
    [][]any{{time.Now(), 100.5}, {time.Now().Add(time.Minute), 101.2}})

// 删除
client.Delete("kline_600519", "ts < '2023-01-01'")
```

## 自动重连机制

- 所有操作（`Exec` / `Query` / `QueryRow` / `Insert` / `Delete` / 建表等）执行前都会调用 `ensureConn()` 探活
- 连接断开（如数据库重启、网络抖动）时，先 Ping 失败 → 关闭旧连接 → 重新建立连接（重新打开 + 建库 + USE）
- 重连过程加锁保护，并发场景下只重建一次
- 若数据库长时间不可用，重连失败会向上返回错误；数据库恢复后下一次操作自动成功

## 注意事项

- TDengine 主键为时间戳，`Insert` 相同时间戳的记录会覆盖旧值（upsert 语义）
- 所有方法并发安全（内部为 `*sql.DB` + 互斥锁）
- `Close` 后客户端不可再使用；`DropDatabase` / `DropStable` 会级联删除其中全部数据，请谨慎使用