stardb/CHANGELOG.MD

Changelog

本文档记录 StarDB 的主要变更。

[Unreleased] - 2026-03-20

Added

• 新增可判定错误类型（errors.Is 友好）：
  • 生命周期：ErrDBNotInitialized ErrTxNotInitialized ErrStmtNotInitialized
  • 参数/目标校验：ErrQueryEmpty ErrTargetNil ErrTargetNotPointer 等
  • 映射与批量写入：ErrColumnNotFound ErrNoInsertValues ErrBatchRowValueCountMismatch 等
• 新增流式查询能力（DB / Tx / Stmt）：
  • QueryRaw / QueryRawContext
  • ScanEach / ScanEachContext
  • ScanEachORM / ScanEachORMContext
• 新增 NULL 安全取值：
  • GetNullString GetNullInt64 GetNullFloat64 GetNullBool GetNullTime
• 新增 ORM 行为开关：
  • SetStrictORM(true) 启用严格列检查
  • ClearReflectCache() 清理反射缓存
• 新增 SQL 运行时可观测能力：
  • Hook：SetSQLHooks SetSQLBeforeHook SetSQLAfterHook
  • 慢 SQL 阈值：SetSQLSlowThreshold
  • 指纹：SetSQLFingerprintEnabled SetSQLFingerprintMode SetSQLFingerprintKeepComments
  • 指纹计数：SetSQLFingerprintCounterEnabled SQLFingerprintCounters ResetSQLFingerprintCounters
  • Context 元信息：SQLHookMetaFromContext BatchExecMetaFromContext
• 新增占位符方言适配：
  • SetPlaceholderStyle(PlaceholderQuestion|PlaceholderDollar)（? / $1,$2...）
• 新增批量插入分片控制：
  • SetBatchInsertMaxRows
  • SetBatchInsertMaxParams
  • 常见驱动参数上限自动识别（SQLite / PostgreSQL / MySQL / SQL Server）

Changed

• 批量写入在开启分片或触发参数阈值时，改为事务内多分片执行，降低单条 SQL 过大风险。
• 分片批量写入结果语义明确：
  • RowsAffected() 返回分片累计值
  • LastInsertId() 返回最后一个分片的 insert id
• 内部结构按模块归档到 internal/，保持外部 API 稳定：
  • internal/convert
  • internal/scanutil
  • internal/sqlplaceholder
  • internal/sqlruntime
• README 重写为面向使用场景的说明，补齐能力边界、接入顺序和 API 细节。

Behavior Notes

• 默认查询 Query 仍为内存模式（解析到 StarRows）。
• 关闭内存预读时，使用 QueryRaw / ScanEach / ScanEachORM。
• SQL Hook、指纹与指纹计数默认关闭，需显式开启。
• 批量分片关闭条件：maxRows <= 0 且 maxParams <= 0 且未命中驱动自动阈值。

Tests

• 新增/补强测试覆盖：
  • 流式查询与流式 ORM
  • NULL 安全取值
  • 严格 ORM 行为
  • 占位符转换
  • SQL Hook、慢 SQL 阈值、指纹模式、注释保留开关、指纹计数
  • BatchInsert 分片（按行数/参数）、失败回滚与结果语义