# 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 分片（按行数/参数）、失败回滚与结果语义