# taibai-go

**Repository Path**: coraldane/taibai-go

## Basic Information

- **Project Name**: taibai-go
- **Description**: No description available
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-16
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# taibai-go

Taibai 数据库的 Go 语言驱动，类似于 JDBC 的角色。采用高效的二进制协议进行通信。

## 特性

- 支持 Go 标准 `database/sql` 接口
- 高性能二进制协议传输
- 支持事务（BEGIN/COMMIT/ROLLBACK）
- 连接池友好
- TLS 加密支持

## 安装

```bash
go get gitee.com/coraldane/taibai-go
```

## 快速开始

### 使用 database/sql 标准接口

```go
import (
    "database/sql"
    _ "gitee.com/coraldane/taibai-go"
)

func main() {
    // 连接数据库
    db, err := sql.Open("taibai", "taibai://user:password@localhost:5151/default")
    if err != nil {
        log.Fatal(err)
    }
    defer db.Close()

    // 查询
    rows, err := db.Query("SELECT id, name FROM users")
    if err != nil {
        log.Fatal(err)
    }
    defer rows.Close()

    for rows.Next() {
        var id int64
        var name string
        rows.Scan(&id, &name)
        fmt.Printf("id=%d, name=%s\n", id, name)
    }
}
```

### 使用原生 API（更高性能）

```go
import taibai "gitee.com/coraldane/taibai-go"

func main() {
    // 连接数据库
    conn, err := taibai.Connect("localhost:5151", taibai.Config{
        Username: "default",
        Password: "",
        Database: "default",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer conn.Close()

    // 使用二进制协议查询（高性能）
    result, err := conn.QueryBinary("SELECT id, name FROM users LIMIT 10")
    if err != nil {
        log.Fatal(err)
    }

    // 遍历结果
    for row := result.Rows(); row.Next(); {
        var id int64
        var name string
        row.Scan(&id, &name)
        fmt.Printf("id=%d, name=%s\n", id, name)
    }
}
```

### 事务处理

```go
conn, _ := taibai.Connect("localhost:5151", taibai.Config{})
defer conn.Close()

// 开始事务
conn.Begin()

// 执行语句
conn.Execute("INSERT INTO users (name) VALUES ('Alice')")
conn.Execute("INSERT INTO users (name) VALUES ('Bob')")

// 提交事务
conn.Commit()

// 或回滚: conn.Rollback()
```

## DSN 格式

```
taibai://[user[:password]@]host[:port]/database[?param=value&...]
```

支持的参数：
- `timeout` / `connect_timeout` - 连接超时
- `read_timeout` - 读取超时
- `write_timeout` - 写入超时
- `binary` - 是否使用二进制协议 (true/false)
- `tls` - 是否启用 TLS (true/false)

示例：
```
taibai://localhost:5151/default
taibai://user:pass@localhost:5151/mydb
taibai://user:pass@localhost:5151/mydb?timeout=10s&binary=true
```

## 协议说明

taibai-go 使用自定义二进制协议与 Taibai 数据库通信：

- **协议头**: 14 字节 (Magic + Version + Type + Flags + Length)
- **Magic Number**: `0x54414942` ("TAIB")
- **支持的消息类型**:
  - Handshake (握手认证)
  - Query (SQL 查询)
  - BinaryQueryResult (二进制结果集)
  - BeginTxn/CommitTxn/RollbackTxn (事务控制)
  - Ping/Pong (心跳)

## 数据类型映射

| Taibai 类型 | Go 类型 |
|------------|---------|
| INT64      | int64   |
| INT32      | int32   |
| FLOAT64    | float64 |
| FLOAT32    | float32 |
| STRING     | string  |
| BOOL       | bool    |
| TIMESTAMP  | time.Time |

## 高级功能

### 连接池

```go
cfg := taibai.DefaultPoolConfig()
cfg.Host = "localhost"
cfg.Port = 5151
cfg.MaxOpenConns = 10
cfg.MaxIdleConns = 5

pool, err := taibai.NewPool(cfg)
if err != nil {
    log.Fatal(err)
}
defer pool.Close()

// 获取连接
conn, err := pool.Get(context.Background())
if err != nil {
    log.Fatal(err)
}
defer conn.Close() // 返回连接池

result, _ := conn.QueryBinary("SELECT * FROM users")
```

### Prepared Statement

```go
// 位置参数 ($1, $2, ...)
stmt, _ := conn.Prepare("SELECT * FROM users WHERE id = $1 AND name = $2")
result, _ := stmt.Query(1, "Alice")

// 命名参数 (:name)
namedStmt, _ := conn.PrepareNamed("INSERT INTO users VALUES (:id, :name)")
namedStmt.Exec(map[string]interface{}{
    "id":   1,
    "name": "Alice",
})
```

### 批量插入

```go
bulk := conn.NewBulkInsert("users", []protocol.DataType{
    protocol.DataTypeInt64,
    protocol.DataTypeString,
})
bulk.SetMaxRows(10000) // 每批最大行数

for i := 0; i < 100000; i++ {
    bulk.AddRow(int64(i), fmt.Sprintf("user%d", i))
}
bulk.Close() // 刷新剩余数据
```

### Context 支持

```go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

result, err := conn.QueryBinaryContext(ctx, "SELECT * FROM large_table")
if err == context.DeadlineExceeded {
    log.Println("Query timed out")
}
```

## 项目结构

```
taibai-go/
├── go.mod              # Go 模块定义
├── taibai.go           # database/sql 驱动注册
├── driver.go           # database/sql 接口实现
├── config.go           # 配置和 DSN 解析
├── conn.go             # 连接管理
├── context.go          # Context 支持
├── query.go            # SQL 执行和结果集
├── stmt.go             # Prepared Statement
├── pool.go             # 连接池
├── bulk.go             # 批量插入
└── protocol/           # 二进制协议
    ├── constants.go    # 协议常量
    ├── message.go      # 消息读写
    ├── encoding.go     # 编解码
    └── result.go       # 结果集解码
```

## 错误处理

```go
result, err := conn.Execute("SELECT * FROM nonexistent")
if err != nil {
    var tErr *taibai.Error
    if errors.As(err, &tErr) {
        fmt.Printf("Error code: %d, message: %s\n", tErr.Code, tErr.Message)
    }
    
    // 检查特定错误类型
    if taibai.IsTableNotFound(err) {
        fmt.Println("Table not found")
    }
    
    // 检查是否可重试
    if taibai.IsRetryable(err) {
        // 重试逻辑
    }
}
```

## 重试机制

```go
ctx := context.Background()
cfg := taibai.DefaultRetryConfig()
cfg.MaxRetries = 5

result, err := conn.QueryWithRetry(ctx, cfg, "SELECT * FROM users")
```

## 日志

```go
// 启用调试日志
taibai.EnableDebugLogging()

// 启用信息日志
taibai.EnableInfoLogging()

// 禁用日志
taibai.DisableLogging()

// 自定义日志
taibai.SetLogger(myCustomLogger)
```

## 健康检查

```go
// 创建健康检查器
checker := taibai.NewHealthChecker(pool, taibai.DefaultHealthConfig())
checker.Start()
defer checker.Stop()

// 检查健康状态
if checker.IsHealthy() {
    fmt.Println("Pool is healthy")
}

// 获取统计
stats := checker.Stats()
fmt.Printf("Total checks: %d, Failed: %d\n", stats.TotalChecks, stats.FailedChecks)
```

## 指标收集

```go
// 获取全局指标
snapshot := taibai.GlobalMetrics.Snapshot()
fmt.Printf("Queries: %d, Success rate: %.2f%%\n", 
    snapshot.QueriesTotal, 
    snapshot.QuerySuccessRate()*100)
fmt.Printf("Avg query duration: %v\n", snapshot.AvgQueryDuration())

// 重置指标
taibai.GlobalMetrics.Reset()
```

## 运行测试

```bash
# 单元测试
go test ./...

# 集成测试（需要运行 Taibai 服务）
TAIBAI_DSN="taibai://localhost:5151/default" go test -tags=integration -v
```

## 完整项目结构

```
taibai-go/
├── go.mod              # Go 模块
├── README.md           # 文档
├── taibai.go           # database/sql 驱动注册
├── driver.go           # database/sql 接口实现
├── config.go           # 配置和 DSN 解析
├── conn.go             # 连接管理
├── context.go          # Context 支持
├── query.go            # SQL 执行和结果集
├── stmt.go             # Prepared Statement
├── pool.go             # 连接池
├── bulk.go             # 批量插入
├── errors.go           # 错误类型
├── logger.go           # 日志支持
├── retry.go            # 重试机制
├── health.go           # 健康检查
├── metrics.go          # 指标收集
└── protocol/           # 二进制协议
    ├── constants.go
    ├── message.go
    ├── encoding.go
    └── result.go
```

## 服务端 Prepared Statement

```go
// 创建服务端预编译语句
stmt, err := conn.PrepareServer("SELECT * FROM users WHERE id = $1")
if err != nil {
    log.Fatal(err)
}
defer stmt.Close()

// 执行
result, err := stmt.Exec(1)

// 语句缓存
cache := conn.NewStmtCache(100)
stmt, _ := cache.Get("SELECT * FROM users WHERE id = $1")
```

## 游标（流式结果集）

```go
// 创建游标，每次获取 1000 行
cursor, err := conn.QueryCursor("SELECT * FROM large_table", taibai.CursorOptions{
    FetchSize: 1000,
})
if err != nil {
    log.Fatal(err)
}
defer cursor.Close()

// 流式读取
for cursor.Next() {
    var id int64
    var name string
    cursor.Scan(&id, &name)
}
```

## TLS 加密连接

```go
cfg := taibai.Config{
    Host:       "localhost",
    Port:       5151,
    TLSEnabled: true,
}

// 或使用 DSN
db, _ := sql.Open("taibai", "taibai://localhost:5151/db?tls=true")
```

## 压缩

```go
// 启用 Gzip 压缩
taibai.EnableGzipCompression(6)

// 启用 Zlib 压缩
taibai.EnableZlibCompression(6)

// 禁用压缩
taibai.DisableCompression()
```

## 高精度数值 (Decimal)

```go
d1, _ := taibai.NewDecimal("12345.6789")
d2, _ := taibai.NewDecimal("51515.4321")

sum := d1.Add(d2)
product := d1.Mul(d2)
rounded := d1.Round(2)

fmt.Println(sum.String())     // "111111.1110"
fmt.Println(d1.Float64())     // 12345.6789
```

## UUID

```go
u, _ := taibai.NewUUID("550e8400-e29b-41d4-a716-446655440000")
fmt.Println(u.String())

var nu taibai.NullUUID
nu.Scan("550e8400-e29b-41d4-a716-446655440000")
```

## 负载均衡

```go
cfg := taibai.LoadBalancerConfig{
    Servers: []taibai.ServerConfig{
        {Address: "server1:5151"},
        {Address: "server2:5151"},
        {Address: "server3:5151"},
    },
    Strategy:        taibai.StrategyLeastConn,
    FailoverEnabled: true,
}

lb, _ := taibai.NewLoadBalancer(cfg)
lb.StartHealthCheck()
defer lb.Stop()

// 获取连接（自动选择服务器）
conn, srv, err := lb.ConnectWithFailover(ctx, 3)
defer lb.ReleaseConnection(srv)
```

## 完整项目结构

```
taibai-go/
├── go.mod                  # Go 模块
├── README.md               # 文档
│
├── # 核心
├── taibai.go               # database/sql 驱动注册
├── driver.go               # database/sql 接口
├── config.go               # 配置和 DSN
├── conn.go                 # 连接管理
├── context.go              # Context 支持
├── query.go                # SQL 执行
├── stmt.go                 # 客户端 Prepared Statement
├── prepared.go             # 服务端 Prepared Statement
│
├── # 高级功能
├── pool.go                 # 连接池
├── bulk.go                 # 批量插入
├── batch.go                # 批量执行
├── cursor.go               # 游标/流式结果
├── builder.go              # 查询构建器
├── scanner.go              # 结构体扫描
├── loadbalancer.go         # 负载均衡
│
├── # 数据类型
├── types.go                # Null 类型
├── decimal.go              # Decimal, UUID, Interval
│
├── # 运维
├── errors.go               # 错误类型
├── logger.go               # 日志
├── retry.go                # 重试
├── health.go               # 健康检查
├── metrics.go              # 指标
├── hooks.go                # Hooks/中间件
├── events.go               # 事件系统
├── trace.go                # 链路追踪
├── tls.go                  # TLS 配置
├── compress.go             # 压缩
│
└── protocol/               # 二进制协议
    ├── constants.go
    ├── message.go
    ├── encoding.go
    └── result.go
```

## License

MIT