# toml-db-driver

**Repository Path**: jericho-yu/toml-db-driver

## Basic Information

- **Project Name**: toml-db-driver
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# toml-db-driver 用户指南

`toml-db-driver` 提供代码方式连接 TOML-DB、执行 SQL，并将结果自动填充到多种目标类型（类似 ORM 的 `Scan` 能力）。

## 目录

1. [安装](#1-安装)
2. [创建连接](#2-创建连接)
3. [执行 SQL](#3-执行-sql)
4. [Scan 填充类型](#4-scan-填充类型)
5. [完整示例](#5-完整示例)

---

## 1. 安装

### 1.1 安装

```bash
go get gitee.com/jericho-yu/toml-db-driver@latest
```

### 1.2 创建连接（用户名密码自动登录）

```go
package main

import (
  "fmt"
  "log"

  driver "gitee.com/jericho-yu/toml-db-driver"
)

func main() {
  cli, err := driver.Open(driver.Config{
    HTTPAddr: "http://127.0.0.1:13579",
    Username: "admin",
    Password: "你的密码",
  })
  if err != nil {
    log.Fatal(err)
  }
  defer cli.Close()

  fmt.Println("connected")
}
```

### 1.3 直接执行 SQL

```go
res, err := cli.Exec("SELECT * FROM users LIMIT ?", 5)
if err != nil {
  log.Fatal(err)
}
if !res.OK() {
  log.Fatalf("code=%d msg=%s", res.Code, res.Msg)
}
```

命名参数：

```go
res, err := cli.ExecNamed(
  "SELECT * FROM users WHERE username = :name",
  map[string]any{"name": "alice"},
)
```

### 1.4 Scan 到不同目标类型

假设：

```go
type User struct {
  ID       string `json:"id" toml:"id"`
  Username string `json:"username" toml:"username"`
  Role     string `json:"role" toml:"role"`
}
```

#### 1) `*struct`

```go
res, _ := cli.Exec("SELECT * FROM users WHERE id = ? LIMIT 1", "u001")

var u User
if err := res.Scan(&u); err != nil {
  log.Fatal(err)
}
```

#### 2) `*[]struct`

```go
res, _ := cli.Exec("SELECT * FROM users LIMIT 10")

var list []User
if err := res.Scan(&list); err != nil {
  log.Fatal(err)
}
```

#### 3) `*[]*struct`

```go
res, _ := cli.Exec("SELECT * FROM users LIMIT 10")

var list []*User
if err := res.Scan(&list); err != nil {
  log.Fatal(err)
}
```

#### 4) `*map[string]any`

```go
res, _ := cli.Exec("SELECT * FROM users WHERE id = ? LIMIT 1", "u001")

var m map[string]any
if err := res.Scan(&m); err != nil {
  log.Fatal(err)
}
```

#### 5) `*[]any`

```go
res, _ := cli.Exec("SELECT * FROM users LIMIT 10")

var arr []any
if err := res.Scan(&arr); err != nil {
  log.Fatal(err)
}
```

#### 6) `*any`

```go
res, _ := cli.Exec("SHOW TABLES")

var v any
if err := res.Scan(&v); err != nil {
  log.Fatal(err)
}
```

### 1.5 常见建议

- `Open` 后务必 `defer cli.Close()`。
- `Scan` 前先检查 `res.OK()` 或 `res.Code == 0`。
- 对单条查询建议 SQL 使用 `LIMIT 1`，并扫描到 `*struct` / `*map[string]any`。