# git.fsdpf.net/go/db（master）

数据库访问层，架构上 fork 自 [doug-martin/goqu](https://github.com/doug-martin/goqu)：不是链式
拼字符串的 Builder，而是先构造一棵 `exp` 表达式树，再由方言（dialect）相关的 `sqlgen` 渲染成
具体 SQL + 绑定参数。配合 `req-v2`/`orm-v2` 等 "-v2" 系列项目使用。

## 这个仓库有什么

### 查询构造：`SelectDataset`/`InsertDataset`/`UpdateDataset`/`DeleteDataset`

- `db.From(table ...interface{}) *SelectDataset`：起一个查询，`.Select(...)`/`.Where(...)`/
  `.Join(...)`/`.GroupBy(...)`/`.Order(...)` 等链式方法都是在往同一棵表达式树上追加/替换子句
  （`Clauses`），不是拼字符串，所以中间状态可以安全地复制、按条件分支修改。
- `Executor()`/`ScanStructs`/`ScanStruct`/`GetRecords()`：真正执行查询、把结果扫进结构体或
  `map[string]any`。`ToSQL()` 只生成 SQL 文本，不落库，方便测试断言/调试。
- `.WithHook(hook)`：给这次查询挂一个 `exec.Hooks` 实现（`Before`/`After` 两个阶段），这是
  `req-v2/resx` 包用来做字段级脱敏、行级权限过滤、变更留痕的挂载点——`db-v2` 本身不关心权限，
  只提供"查询执行前后可以介入改写"这个机制。

### 表达式树：`exp` 包

- `exp.IdentifierExpression`（`db.I`/`db.C`/`db.T`，标识符：列/表/schema）、
  `exp.LiteralExpression`（`db.L`/`db.V`，字面量/原样 SQL 片段）、
  `exp.AliasedExpression`（`.As(...)`）、`exp.SQLFunctionExpression`（`db.Func`/`db.COUNT`/
  `db.COALESCE` 等聚合与常用函数）、`exp.CaseExpression`（`db.Case()`）、
  `exp.WindowExpression`（`db.W()`，窗口函数）。
- 这棵树是 immutable/copy-on-write 风格的：每次链式调用返回新的（或者原地更新的）`Clauses`，
  不会有隐式的跨查询共享状态问题。

### 连接与方言

- `engine.Engine`：多连接管理，`engine.Open(cfgs map[string]DBConfig)` 从配置建立连接池，
  `engine.Mock(cfgs map[string]MockDBConfig)` 用 `sqlmock` 建 mock 连接（测试专用）；
  `Engine.Connection(name string) *db.Database` 按连接名取出可以直接 `.From(...)` 发查询的
  `*db.Database`。
- `dialect/mysql`/`dialect/sqlite3`/`dialect/duckdb`：具体方言实现，通过 `import _
  "git.fsdpf.net/go/db/dialect/mysql"` 这种匿名 import 注册进 `sqlgen`，不用的方言不用编译进去。
- `dialect/sqlite3/vtab`：SQLite 虚拟表（Virtual Table）支持，给需要把非关系数据源伪装成表的
  场景用（`sqlite3`/`vtable` build tag 控制是否编译）。

### 建表/迁移：`schema` 包

- `schema.Blueprint`/`ColumnDefinition`：描述表结构（列类型、长度、默认值、可空性等），
  `schema/dialect/*` 按方言生成 `CREATE TABLE`/`ALTER TABLE` 语句。

## 分支状态

`master` 是持续开发中的新架构，**跟老仓库 `v1-legacy` 分支历史不相关**（`db-v2` 是另开的新
项目，不是从老代码库演化过来的），API 完全不兼容。还在用老版 `db.Builder`（`Table`/`Find`/
`Paginate`/`Chunk` 那一套）的老项目，参见 `v1-legacy` 分支。