Golang轻松操作rqlite数据库API的客户端插件go-rqlite使用指南

概述

gorqlite是一个用于rqlite的Go客户端，提供了易于使用的抽象层来操作rqlite API。它提供了专门为rqlite设计的惯用API，以及一个database/sql驱动。

主要特性

• 抽象了rqlite HTTP API交互 - POST请求、JSON处理等
• 提供类似database/sql的语义，如Open()、Query()、QueryOne()、Next()/Scan()/Map()、Write()和WriteOne()等
• 支持rqlite特有的操作：Leader()和Peers()检查集群、SetConsistencyLevel()更改一致性级别
• 支持调试跟踪功能Trace(io.Writer)/Trace(nil)
• 无外部依赖，仅使用标准库函数

安装

go get github.com/rqlite/gorqlite

使用示例

基本连接

// 连接到localhost:4001无认证
conn, err := gorqlite.Open("http://") 

// 使用HTTPS
conn, err := gorqlite.Open("https://") 

// 明确指定地址
conn, err := gorqlite.Open("https://localhost:4001/")

// 带认证的连接
conn, err := gorqlite.Open("https://mary:secret2@localhost:4001/")

// 设置一致性级别
conn, err := gorqlite.Open("https://server2.example.com:4001/?level=weak")

// 设置超时
conn, err := gorqlite.Open("https://localhost:2265/?level=strong&timeout=30")

// 禁用集群发现
conn, err := gorqlite.Open("https://localhost:2265/?disableClusterDiscovery=true")

自定义HTTP客户端

// 创建跳过证书验证的TLS传输
tn := &http.Transport{
    TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
}

// 创建HTTP客户端并传递给库
client := &http.Client{Transport: tn}
conn, err := gorqlite.OpenWithClient("https://localhost:4001/", client)

执行写入操作

// 模拟database/sql Prepare()
statements := make([]string, 0)
pattern := "INSERT INTO secret_agents(id, hero_name, abbrev) VALUES (%d, '%s', '%3s')"
statements = append(statements, fmt.Sprintf(pattern, 125718, "Speed Gibson", "Speed"))
statements = append(statements, fmt.Sprintf(pattern, 209166, "Clint Barlow", "Clint"))
statements = append(statements, fmt.Sprintf(pattern, 44107, "Barney Dunlap", "Barney"))
results, err := conn.Write(statements)

// 处理结果
for n, v := range results {
    fmt.Printf("结果%d影响了%d行\n", n, v.RowsAffected)
    if v.Err != nil {
        fmt.Printf("错误: %s\n", v.Err.Error())
    }
}

// 单条写入并获取最后插入ID
res, err := conn.WriteOne("INSERT INTO foo (name) values ('bar')")
fmt.Printf("最后插入ID: %d\n", res.LastInsertID)

执行查询操作

var id int64
var name string

// 查询单条语句
rows, err := conn.QueryOne("select id, name from secret_agents where id > 500")
fmt.Printf("查询返回%d行\n", rows.NumRows)

// 遍历结果
for rows.Next() {
    err := rows.Scan(&id, &name)
    fmt.Printf("这是第%d行\n", rows.RowNumber)
    fmt.Printf("总共有%d行\n", rows.NumRows)
}

// 使用Map()获取结果
for rows.Next() {
    m, err := rows.Map()
    // m现在是map[列名]interface{}
    id := m["id"].(float64) // JSON数字类型
    name := m["name"].(string)
}

参数化查询

// 参数化写入
wr, err := conn.WriteParameterized(
    []gorqlite.ParameterizedStatement{
        {
            Query:     "INSERT INTO secret_agents(id, name, secret) VALUES(?, ?, ?)",
            Arguments: []interface{}{7, "James Bond", "not-a-secret"},
        },
    },
)

// 参数化查询
qr, err := conn.QueryParameterized(
    []gorqlite.ParameterizedStatement{
        {
            Query:     "SELECT id, name from secret_agents where id > ?",
            Arguments: []interface{}{3},
        },
    },
)

集群信息

// 获取当前Leader
leader, err := conn.Leader()
fmt.Println("当前Leader:", leader)

// 获取所有Peer
peers, err := conn.Peers()
for n, p := range peers {
    fmt.Printf("集群Peer %d: %s\n", n, p)
}

调试跟踪

// 开启调试跟踪到文件
f, err := os.OpenFile("/tmp/deep_insights.log", os.O_RDWR|os.O_CREATE|os.O_APPEND, 0644)
gorqlite.TraceOn(f)

// 改为跟踪到标准错误
gorqlite.TraceOn(os.Stderr)

// 关闭跟踪
gorqlite.TraceOff()

database/sql驱动使用

package main

import (
    "database/sql"
    _ "github.com/rqlite/gorqlite/stdlib"
)

func main() {
    db, err := sql.Open("rqlite", "http://")
    if err != nil {
        panic(err)
    }
    _, err = db.Exec("CREATE TABLE users (id INTEGER, name TEXT)")
    if err != nil {
        panic(err)
    }
}

重要注意事项

1. 如果使用访问控制，连接用户需要_status_权限
2. rqlite不支持迭代获取，查询会将所有结果立即放入内存
3. 在标准database/sql驱动中有一些限制：
   • 事务必须作为单个批处理提交
   • 不支持回滚
   • Prepare()是空操作

完整示例

package main

import (
    "fmt"
    "github.com/rqlite/gorqlite"
    "os"
)

func main() {
    // 1. 连接到rqlite
    conn, err := gorqlite.Open("http://localhost:4001")
    if err != nil {
        fmt.Printf("连接错误: %v\n", err)
        return
    }
    
    // 2. 创建表
    _, err = conn.WriteOne("CREATE TABLE IF NOT EXISTS users (id INTEGER, name TEXT)")
    if err != nil {
        fmt.Printf("创建表错误: %v\n", err)
        return
    }
    
    // 3. 插入数据
    res, err := conn.WriteOne("INSERT INTO users (id, name) VALUES (1, 'Alice')")
    if err != nil {
        fmt.Printf("插入错误: %v\n", err)
        return
    }
    fmt.Printf("插入影响行数: %d\n", res.RowsAffected)
    
    // 4. 查询数据
    rows, err := conn.QueryOne("SELECT id, name FROM users")
    if err != nil {
        fmt.Printf("查询错误: %v\n", err)
        return
    }
    
    for rows.Next() {
        var id int64
        var name string
        err = rows.Scan(&id, &name)
        if err != nil {
            fmt.Printf("扫描错误: %v\n", err)
            continue
        }
        fmt.Printf("ID: %d, Name: %s\n", id, name)
    }
    
    // 5. 获取集群信息
    leader, err := conn.Leader()
    if err != nil {
        fmt.Printf("获取Leader错误: %v\n", err)
    } else {
        fmt.Printf("当前Leader: %s\n", leader)
    }
    
    peers, err := conn.Peers()
    if err != nil {
        fmt.Printf("获取Peers错误: %v\n", err)
    } else {
        fmt.Println("集群Peers:")
        for i, peer := range peers {
            fmt.Printf("  %d: %s\n", i, peer)
        }
    }
}

这个客户端库已被多个组织在生产环境中使用，包括Replicated。它提供了简单易用的API来操作rqlite数据库，适合需要高可用性SQLite解决方案的场景。