Documentation
¶
Overview ¶
Package sql 提供 VDS 的顶层 SQL API，对齐 Go 标准库 database/sql 使用习惯。
基本用法（auto-commit，单语句）：
db := sql.Open(eng)
n, err := db.Exec("INSERT INTO users VALUES (1, 'Alice', 30)")
rows, schema, err := db.Query("SELECT * FROM users WHERE age > 18")
多语句事务：
tx, err := db.Begin()
tx.Exec("INSERT INTO accounts VALUES (1, 1000)")
tx.Exec("UPDATE accounts SET balance = 900 WHERE id = 1")
err = tx.Commit() // 或 tx.Rollback()
Index ¶
- type DB
- func (db *DB) Begin() (*Tx, error)
- func (db *DB) DescribeTable(name string) (*catalog.TableDesc, error)
- func (db *DB) DumpPlanCache() []string
- func (db *DB) Exec(sql string) (int64, error)
- func (db *DB) ExecArgs(sql string, args ...interface{}) (int64, error)
- func (db *DB) ExecBatch(sqls []string) (int64, error)
- func (db *DB) ExecContext(ctx context.Context, sql string, args ...interface{}) (int64, error)
- func (db *DB) ExecResult(sql string, args ...interface{}) (*Result, error)
- func (db *DB) HasTable(name string) (bool, error)
- func (db *DB) ListTables() ([]string, error)
- func (db *DB) ListViews() ([]string, error)
- func (db *DB) Prepare(sql string) (*Stmt, error)
- func (db *DB) Query(sql string) (*Rows, error)
- func (db *DB) QueryAll(sql string) ([]executor.Row, *planner.Schema, error)
- func (db *DB) QueryAllArgs(sql string, args ...interface{}) ([]executor.Row, *planner.Schema, error)
- func (db *DB) QueryArgs(sql string, args ...interface{}) (*Rows, error)
- func (db *DB) QueryContext(ctx context.Context, sql string, args ...interface{}) (*Result, error)
- func (db *DB) QueryResult(sql string, args ...interface{}) (*Result, error)
- func (db *DB) RefreshTableNames()
- func (db *DB) SetDebugLog(fn func(format string, args ...interface{}))
- func (db *DB) Stats() (DBStats, error)
- func (db *DB) ViewDefinition(name string) (string, error)
- type DBStats
- type Result
- type Rows
- type Stmt
- type Tx
- func (tx *Tx) Commit() error
- func (tx *Tx) Exec(sql string) (int64, error)
- func (tx *Tx) ExecArgs(sql string, args ...interface{}) (int64, error)
- func (tx *Tx) ExecResult(sql string, args ...interface{}) (*Result, error)
- func (tx *Tx) Query(sql string) (*Rows, error)
- func (tx *Tx) QueryAll(sql string) ([]executor.Row, *planner.Schema, error)
- func (tx *Tx) QueryAllArgs(sql string, args ...interface{}) ([]executor.Row, *planner.Schema, error)
- func (tx *Tx) QueryArgs(sql string, args ...interface{}) (*Rows, error)
- func (tx *Tx) QueryResult(sql string, args ...interface{}) (*Result, error)
- func (tx *Tx) Rollback() error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB VDS SQL 层顶层入口，负责 parse → plan → execute 的完整流程。 并发安全：多个 goroutine 可并发调用 DB 的方法。
并发策略：
- planMu（sync.RWMutex）：RLock 保护缓存命中路径，Lock 保护缓存重建路径
- parserPool（sync.Pool）：消除 parser data race，每个 goroutine 从池中取独立 parser
- schemaEpoch：Catalog 的原子计数器，DDL 后自动失效所有缓存计划
func OpenCluster ¶
OpenCluster 创建集群模式 DB 实例，使用自定义的事务工厂。
func (*DB) DescribeTable ¶ added in v1.1.3
DescribeTable 返回表的完整元数据（列、索引）。 表不存在时返回 (nil, nil)，与 catalog.GetTable 语义一致。
func (*DB) DumpPlanCache ¶ added in v1.1.9
DumpPlanCache 返回计划缓存的完整内容，用于调试。 每行格式: "key=<sql> epoch=<N>"，外加 catalog epoch 和总条目数。
func (*DB) ExecContext ¶ added in v1.2.0
ExecContext 执行带 context 的 DML/DDL 语句，支持查询取消。 ctx 会传播到全表扫描等长时间运行的算子中，取消 ctx 后扫描会尽早停止。
func (*DB) ExecResult ¶ added in v1.1.6
ExecResult 执行 DML/DDL 并返回完整 Result(含 LastInsertId).
func (*DB) ListTables ¶ added in v1.1.3
ListTables 返回数据库中所有用户表名，按创建顺序排列。 从 Catalog 内存注册表读取，O(1) 操作，零 B+Tree 访问。
func (*DB) Prepare ¶
Prepare 预编译 SQL 语句，返回可复用的 Stmt。 后续 Exec/Query 跳过 parse→plan→optimize，节省 ~30% 单次执行开销。
func (*DB) QueryAllArgs ¶ added in v1.1.9
func (db *DB) QueryAllArgs(sql string, args ...interface{}) ([]executor.Row, *planner.Schema, error)
QueryArgs 执行带参数的 SELECT 语句（M2 新增）。 args 为 SQL 中 ? 占位符的绑定值，无参数时传 nil。
func (*DB) QueryContext ¶ added in v1.2.0
QueryContext 执行带 context 的 SELECT 语句，支持查询取消。 ctx 会传播到全表扫描等长时间运行的算子中。
func (*DB) QueryResult ¶ added in v1.1.1
QueryResult 执行带参数的 SELECT 语句，返回完整 Result（含 Truncated 标志）。 当结果集超过 maxQueryRows 行时，Result.Truncated = true，仅返回前 maxQueryRows 行。
func (*DB) RefreshTableNames ¶ added in v1.2.6
func (db *DB) RefreshTableNames()
RefreshTableNames 从 B+Tree 重新扫描表名，更新内存索引。 由 Raft FSM.Apply 回调调用，确保 follower 的 catalog 内存与 B+Tree 同步（CL-05 修复）。
func (*DB) SetDebugLog ¶ added in v1.1.9
SetDebugLog 设置诊断日志回调，用于排查查询执行路径问题。 设置后每个 SELECT 的扫描算子会输出 key range、MVCC 可见性等调试信息。
type DBStats ¶ added in v1.1.3
type DBStats struct {
// TableCount 用户表数量
TableCount int
// TotalRows 所有表行数之和（来自内存统计缓存，非全表扫描，O(n) n=表数）
TotalRows int64
}
DBStats 数据库整体统计信息。 与 database/sql.DBStats 命名风格对齐（值类型，非指针）。
type Result ¶
type Result struct {
// Rows 查询返回的行（DML/DDL 为空）
Rows []executor.Row
// Schema 结果集的列描述（DML/DDL 为 nil）
Schema *planner.Schema
// RowsAffected 受影响行数（Exec 时有效，Query 时为 0）
RowsAffected int64
// LastInsertId AUTO_INCREMENT 列最后插入的 ID（仅 INSERT 有效）
LastInsertId int64
// Truncated 结果集超过 maxQueryRows 行时为 true，仅返回前 maxQueryRows 行。
// 调用方可据此提示用户使用 LIMIT 或改用流式 QueryRows API。
Truncated bool
}
Result SQL 执行结果
type Rows ¶
type Rows struct {
// contains filtered or unexported fields
}
Rows 流式查询结果迭代器，逐行消费结果集。 与 Query() 全量加载不同，Rows 每次只从算子树拉取一行， 适合大结果集场景。使用完必须调用 Close() 提交事务。
type Stmt ¶
type Stmt struct {
// contains filtered or unexported fields
}
Stmt 预编译 SQL 语句——跳过重复的 Parse→Plan→Optimize。 通过 db.Prepare() 创建，多次 Exec/Query 共享缓存的物理计划。
func (*Stmt) Close ¶ added in v1.2.0
Close 关闭预编译语句，释放缓存的物理计划和内部引用。幂等。 调用后 Stmt 不可再使用，后续 Exec/Query 将返回 ErrStmtClosed。
func (*Stmt) ExecResult ¶ added in v1.1.6
ExecResult 使用预编译语句执行 DML/DDL, 返回完整 Result(含 LastInsertId).
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx 表示一个显式 SQL 事务，对齐 database/sql.Tx。
func (*Tx) ExecResult ¶ added in v1.1.6
ExecResult 在事务中执行 DML/DDL, 返回完整 Result(含 LastInsertId).
func (*Tx) Query ¶
QueryRows 在事务内执行 SELECT 并返回流式 Rows 迭代器。 迭代器与该事务共享同一底层 txn，Close() 不提交事务（由 Tx.Commit/Rollback 管理）。
func (*Tx) QueryAllArgs ¶ added in v1.1.9
func (tx *Tx) QueryAllArgs(sql string, args ...interface{}) ([]executor.Row, *planner.Schema, error)
QueryArgs 在事务中执行带参数的 SELECT 语句（M2 新增）。
func (*Tx) QueryResult ¶ added in v1.1.6
QueryResult 在事务中执行 SELECT，返回含截断标志的完整结果。
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package catalog 管理 VDS 数据库的元数据（表描述符和统计信息）。
|
Package catalog 管理 VDS 数据库的元数据（表描述符和统计信息）。 |
|
Package encoder 实现 VDS SQL 层的行编码/解码与 key 编码工具。
|
Package encoder 实现 VDS SQL 层的行编码/解码与 key 编码工具。 |
|
agg.go 实现聚合算子 AggOp（GROUP BY + COUNT/SUM/AVG/MAX/MIN + HAVING）
|
agg.go 实现聚合算子 AggOp（GROUP BY + COUNT/SUM/AVG/MAX/MIN + HAVING） |
|
Package expr 定义 VDS SQL 层的表达式接口和基础表达式类型。
|
Package expr 定义 VDS SQL 层的表达式接口和基础表达式类型。 |
|
Package parser 封装 TiDB SQL 解析器，提供 VDS SQL 层使用的 AST 类型。
|
Package parser 封装 TiDB SQL 解析器，提供 VDS SQL 层使用的 AST 类型。 |
|
builder.go 将 TiDB AST 转换为 LogicalPlan
|
builder.go 将 TiDB AST 转换为 LogicalPlan |
|
Package types 定义 VDS SQL 层的类型系统。
|
Package types 定义 VDS SQL 层的类型系统。 |