MetonaSqlark/CHANGELOG.md

Changelog

All notable changes to MetonaSqlark will be documented in this file.

[0.2.5] - 2026-07-29

Fixed

• 版本号统一 — constants.ts VERSION 从 '0.2.0' 更新为 '0.2.5'，修正 index.ts/utils.ts/CONTRIBUTING.md 中过时的版本注释和数据
• AriaEngine OPFS 后端映射 — core.ts 中 mode: 'aria' + diskEngine: 'opfs' 时实际使用 Memory 后端的 bug 已修复
• _onError 接入执行路径 — query()/defineTable()/dropTable()/transaction()/importTable() 的 catch 路径现在调用 _onError 全局错误回调
• maxRowsPerQuery 生效 — QueryExecutor 构造时接收 maxRowsPerQuery 参数，SELECT 结果在返回前截断
• WAL full 模式真正同步 — WAL.append() 改为 async，full 模式下 await this.store.append() 真正等待写入完成，不再 fire-and-forget
• PluginManager.install 传 db 实例 — register() 增加可选 db 参数，core.ts 初始化时传入 this，插件可获取 db 引用

Changed

• SSTableReader 二分查找统一 — locateBlockGE/locateBlockLE 从线性扫描改为二分查找，rangeScan 性能在大型 SSTable 下不再退化
• crypto 实例化 — 全局状态改为 CryptoManager 类，每个 AriaEngine 实例可拥有独立加密配置，保留全局函数向后兼容
• compactLevelSync 接口公开化 — LSM 新增 public compactLevel() 方法，vacuum() 不再使用 as any 绕过 private 访问
• WAL 大小阈值接入 checkpoint — CheckpointManager 接收 walSizeThreshold 参数，WAL 缓冲超阈值时自动触发 checkpoint

Added

• ALTER TABLE 语法 — 支持 ALTER TABLE ... ADD COLUMN / DROP COLUMN（含可选 COLUMN 关键字）
• TRUNCATE TABLE 语法 — 支持 TRUNCATE TABLE name 快速清空表数据
• MVCC 接入读写路径 — 事务内 insert/update/delete 调用 mvcc.writeVersion/mvcc.deleteVersion，版本链作为 undo log
• IndexedDB 索引利用 — IndexedDBEngine.find 等值查询时优先使用 IDB 索引（idx_col 命名约定），避免全量 getAll
• SQL 注入防护 — React useTable / Vue useSqlarkTable 增加表名合法性校验（/^[a-zA-Z_][a-zA-Z0-9_]*$/）

---

[0.2.4] - 2026-07-27

Added

• 二级索引 — 每列可独立维护 LSM Tree 索引，$eq/$in/$gt/$lt 走索引 O(log n)
• MVCC 接入引擎 — MVCCManager 正式投产，替换 ad-hoc txnSnapshot
• MVCC 自动 GC — 每 10 次 checkpoint 自动回收过旧版本（保留最新 100 个）
• Bloom Filter 序列化 — 写入 SSTable footer + 读取时加载 + 查询时 probe 快速否定
• WAL 大小阈值 — walSizeThreshold 配置（默认 16MB），超阈值强制 checkpoint
• 内存预算 — maxMemoryMB 配置（默认 64MB）

Changed

• WAL 默认同步模式 — walSyncMode 从 'batch' 改为 'full'，消除 crash 丢数据风险
• 查询优化 — tryIndexLookup 扩展支持非 PK 列索引查找

---

[0.2.3] - 2026-07-27

Fixed

• RB-Tree fixDelete 完整实现 — 补全标准红黑树删除修复，保证 O(log n)
• LSM SSTable 缓存预热 — init() 预加载所有 SSTable，消除 cache miss
• OPFS 数据恢复 — open() 自动从 OPFS 文件加载已有表数据到内存
• Aria WAL 事务恢复 — 两阶段恢复：仅回放已提交事务，未提交数据不回放
• LZ4 格式修复 — 重写 token 格式，消除中间字面量 token 歧义

---

[0.2.2] - 2026-07-27

Added

• OPFS 自研存储后端 — AriaEngine 新增 OPFSBackend，纯浏览器文件系统 API，零 IndexedDB 依赖
  • 每个 key 对应一个二进制文件，存储在 navigator.storage.getDirectory() 下
  • 支持 read/write/delete/list/exists/clear 完整接口
  • 页面文件（4KB）、WAL 日志、Schema、SSTable 全部存储为独立文件
  • { dbName }/pg_1, { dbName }/__wal_0, { dbName }/__aria_schemas ...

Changed

• AriaEngineConfig.storageBackend 已支持 'opfs'，AriaEngine.open() 自动选择 OPFSBackend

---

[0.2.1] - 2026-07-27

Fixed

• WAL CRC 校验验证 — 恢复时计算并验证 CRC32，损坏记录自动跳过并告警
• Hybrid 引擎提交顺序 — commit 先写磁盘再写内存，磁盘失败回滚内存，消除数据不一致风险
• RESTRICT 外键行为修正 — 检测到引用行时抛出 FOREIGN_KEY_VIOLATION，不再静默保留孤儿
• SSTable rangeScan 边界保护 — 空索引或 startBlockIdx > endBlockIdx 时安全返回

Added

• ColumnDef 约束激活 — maxLength/min/max 约束在 checkFieldType 中正式生效
• 查询结果上限 — DatabaseConfig.maxRowsPerQuery（默认 0 不限制），防止超大结果集 OOM
• onError 全局回调 — 配置中的 onError 回调实际接入 CRUD 异常路径
• debug 调试模式 — DatabaseConfig.debug: true 输出 [MetonaSqlark:name] 前缀的结构化日志
• 浏览器兼容性声明 — README 增加 Chrome 80+/Firefox 80+/Safari 14+/Edge 80+ 支持矩阵

Changed

• MemoryEngine RESTRICT 外键行为：从"不级联保留孤儿"改为"禁止删除抛异常"
• Hybrid 引擎 commitTransaction 磁盘优先于内存
• DB_DEFAULTS 新增 maxRowsPerQuery: 0 和 debug: false

---

[0.2.0] - 2026-07-27

Added

• AriaEngine 自研存储引擎 — 基于 LSM-Tree 的页面式存储引擎，19 个新模块，~3500 行 TypeScript
  • 页面格式层 (page/): 4KB Slotted Page 编解码、Tuple 二进制序列化、CRC32 校验
  • Buffer Pool (buffer/): LRU 页面缓存 + 驱逐策略，可控内存占用
  • LSM-Tree 索引 (index/): MemTable (红黑树) + 多级 SSTable + Leveled Compaction
  • Bloom Filter (index/bloom.ts): FNV-1a + Murmur 双哈希，快速键否定判定
  • SSTable 构建器/读取器 (index/sstable_builder.ts, sstable.ts): 二分查找 + 范围扫描
  • Merge Iterator (index/merge_iterator.ts): 最小堆多路归并，去重保留最新值
  • WAL (wal/): 二进制日志格式 (LSN/type/txnId/table/key/json/CRC) + Checkpoint 管理
  • MVCC (transaction/mvcc.ts): 版本链 + 快照隔离 + GC
  • 存储后端 (store/): IndexedDB / Memory 双后端抽象
  • LZ4 压缩 (compression/lz4.ts): 简易页面级压缩
• mode: 'aria' — 新增存储模式，可通过 MetonaSqlark.create({ mode: 'aria' }) 激活
• Schema 持久化 — 表结构自动保存到 __aria_schemas，重启自动恢复
• SSTable 元数据管理 — SSTable 索引信息持久化，启动时自动扫描加载
• 事务感知 CRUD — insert/update/delete 在事务中缓冲到 snapshot，commit 批量写入 LSM
• 244 个 AriaEngine 专项测试 — 覆盖生命周期/表管理/CRUD/事务/持久化/SQL 集成/页面格式/LSM/压缩

Changed

• StorageMode 类型新增 'aria'
• STORAGE_MODES 数组新增 'aria'
• createEngine() 支持 mode: 'aria' 分支
• 测试从 318 → 526，套件从 20 → 27
• 新增 7 个模块级测试文件：aria-page、aria-index、aria-sstable、aria-buffer、aria-wal-mvcc、aria-compress、aria
• LRUList 修复 size 追踪 bug
• WAL 存储改为按记录独立 key（避免拼接缓冲区越界）
• CheckpointManager 解耦 BufferPool 依赖

Fixed

• LZ4 压缩无限循环 — 字面量分支在发现匹配后回退导致 litLen=0 死循环，CI 卡死根因
• SSTableReader.get() 自比较 bug — 参数 key 被循环变量遮蔽导致永远返回第一条
• CheckpointManager 测试 null 引用 — 改为 Mock 对象避免 TypeError 导致进程无法退出
• IndexedDB 持久化测试 — 替换为 Memory Backend 验证，消除 fake-indexeddb timer 堆积
• LSM.flush() 不必要 setTimeout — 替换为 Promise.resolve()，消除额外 timer 延迟

---

[0.1.14] - 2026-07-26

Fixed

• IndexedDB 事务原子性: flushToIDB 改为单 IDB 事务包裹 clear+insert，消除崩溃丢数据风险
• 多标签页冲突: open() 添加 onversionchange 监听，其他标签页升级版本时自动关闭过期连接
• Memory 引擎幂等: open() 重复调用安全无副作用
• 关闭时清理 onversionchange 监听器，防止内存泄漏

---

[0.1.13] - 2026-07-26

Added

• 事务回滚机制: IStorageEngine 新增 beginTransaction/commitTransaction/rollbackTransaction 接口
  • MemoryEngine: 快照式回滚（深拷贝 tables/schemas/indexes）
  • IndexedDBEngine: 延迟写入策略（事务中仅写内存，commit 批量刷 IDB）
  • OPFSEngine: 快照式回滚（commit 批量写文件）
  • HybridEngine: 同时代理内存+磁盘引擎事务
• 子查询支持: SQL Parser + Executor 支持 IN (SELECT ...) 和 op (SELECT ...) 子查询
  • AST 新增 SubqueryExpression 类型
  • Parser 在 IN 和比较运算符后检测子查询
  • Executor 新增 resolveSubqueries() 递归解析，自动执行子查询并替换为具体值
• 外键级联操作: ColumnDef 新增 onDelete/onUpdate 选项
  • 支持 CASCADE（递归级联删除）、SET NULL、RESTRICT
  • SQL Parser 解析 REFERENCES table(col) ON DELETE CASCADE ON UPDATE CASCADE
  • MemoryEngine 内置 cascadeDelete() 递归级联逻辑
• 连接池管理: MetonaSqlark.connect() 静态方法
  • 同名数据库复用已打开实例，引用计数管理
  • db.disconnect() 释放连接，归零自动 close
  • MetonaSqlark.disconnectAll() 强制关闭所有连接

Changed

• TransactionManager.execute() 调用引擎层 begin/commit/rollback 实现真正原子性
• IndexedDBEngine CRUD 事务感知：活跃事务中延迟 IDB 写入
• ASTColumnDef / astColumnToColumnDef 支持 references/onDelete/onUpdate 透传

Fixed

• IndexedDBEngine 事务中 find/count 从内存缓存读取（保证读到未提交变更）
• SQL Parser parseColumnDef 循环条件扩展，避免 REFERENCES 语法解析中断

---

[0.1.12] - 2026-07-26

Added

• MeSqlark 别名导出，与 MetonaSqlark 完全等价
• metona-sqlark.cjs.js CommonJS 构建产物
• 完善的 where-matcher.ts 消除 220+ 行重复代码
• $col 列引用支持 JOIN ON 条件
• $and/$or 嵌套支持（字段级 + 顶层）
• $not 逻辑非操作符
• $like 正则缓存加速
• projectColumns 列投影支持 table.column 格式
• DISTINCT 去重支持（O(n) 时间，列值拼接优化）
• 测试覆盖率提升至 93.46%（264 测试/15 套件）

Changed

• where-matcher 统一 MemoryEngine / IndexedDBEngine / Executor 的 WHERE 逻辑
• JOIN ON 匹配支持 $col 语法
• LIKE 正则改为缓存式编译
• Executor DISTINCT 用列值拼接代替 JSON.stringify
• JOIN 嵌套循环连接优化：避免 ON 时对象扩散

Fixed

• IndexedDBEngine update/delete 方法正确同步内存缓存
• OPFSEngine getTableNames 兼容 entries() 返回值
• SQL Parser 正确处理字符串转义字符
• SQL Parser 正确处理表别名（无 AS 关键字）
• SQL Parser 解析 IS NULL / IS NOT NULL / NOT LIKE
• peekTokenIs 方法正确暴露给语法分析
• 多处边界条件空值/假值处理

---

[0.1.11] - 2026-07-25

Added

• React 集成 hooks: useQuery, useTable, useDatabase
• Vue 集成 composables: useSqlarkQuery, useSqlarkTable, useSqlarkDatabase
• 发布订阅系统: subscribe(), emit()
• 数据迁移系统: addMigration(), migrateTo()
• 导入导出: exportTable(), exportAll(), importTable()
• 完整 SQL 解析器: Lexer + Parser（递归下降）
• SQL 支持: SELECT, INSERT, UPDATE, DELETE, CREATE TABLE, DROP TABLE
• JOIN 支持: INNER, LEFT, RIGHT, CROSS
• GROUP BY + HAVING + 聚合函数 (COUNT, SUM, AVG, MIN, MAX)
• DISTINCT, ORDER BY, LIMIT, OFFSET
• WHERE 条件: AND, OR, NOT, IN, LIKE, IS NULL
• Query Builder 链式 API: select().where().orderBy().limit().execute()
• 插件系统: 14 种生命周期钩子 + PluginManager
• Metadata 系统: ColumnDef 完整约束 (type/primaryKey/required/unique/index/default/references/maxLength/min/max)

Changed

• 架构重构为分层设计：Engine → QueryExecutor → Table/QueryBuilder → SQL Parser → Public API
• AST 作为统一中间表示，SQL 和 QueryBuilder 行为完全一致
• 测试框架完善：core / edge / groupby / join / query-system / sql / table / engine / transaction / plugin / hybrid 全覆盖

---

[0.0.1] - 2026-07-24

Added

• 初始项目骨架
• TypeScript 配置（严格模式）
• Rollup 构建（UMD / ESM / CJS / min / .d.ts）
• Jest + jsdom 测试环境
• ESLint + @typescript-eslint
• Gitea Actions CI 工作流
• 示例站点（index / demo / docs）
• 构建脚本 build.sh