docs: 全站点版本迭代至 v0.5.1 + 功能描述与实现对齐（移除已删 utils/Slotted 宣称、补加密/页面化/锁/维护语句、修正 walSyncMode 默认值、数字校准 1009 测试/87.3%）
This commit is contained in:
thzxx
+590
-590
File diff suppressed because it is too large
Load Diff
@@ -1,10 +1,10 @@
|
||||
# MetonaSqlark
|
||||
|
||||
<p align="center">
|
||||
<img src="https://img.shields.io/badge/version-0.5.0-blue?style=flat-square" alt="version">
|
||||
<img src="https://img.shields.io/badge/version-0.5.1-blue?style=flat-square" alt="version">
|
||||
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
|
||||
<img src="https://img.shields.io/badge/coverage-86.7%25-brightgreen?style=flat-square" alt="coverage">
|
||||
<img src="https://img.shields.io/badge/tests-1022%20passed-success?style=flat-square" alt="tests">
|
||||
<img src="https://img.shields.io/badge/coverage-87.3%25-brightgreen?style=flat-square" alt="coverage">
|
||||
<img src="https://img.shields.io/badge/tests-1009%20passed-success?style=flat-square" alt="tests">
|
||||
</p>
|
||||
|
||||
> 基于 TypeScript 的**前端关系型数据库**，支持完整 SQL 查询、Query Builder 链式 API、与 **AriaEngine 自研存储引擎**。
|
||||
@@ -17,6 +17,7 @@
|
||||
- 💾 **OPFS 自研存储后端** — 纯浏览器文件系统，零 IndexedDB 依赖，二进制页面文件，schema 持久化，单文件 COW 原子写，崩溃残留自动清理
|
||||
- 🔒 **生产级数据安全** — WAL 原子写入 + 标准 CRC32 完整性校验（SSTable 整文件校验 + WAL 记录校验）、**全库 AES-256-GCM 透明加密**（PBKDF2 密钥派生 + salt 持久化 + 密码验证，v0.5.0 真实接线）、`RESTRICT` 外键约束、崩溃恢复自愈
|
||||
- 🔐 **多标签页独占锁** — Web Locks API，第二个标签页打开同一库抛 `ARIA_LOCKED`（v0.5.0）
|
||||
- 🛠 **维护语句 SQL 入口** — `EXPLAIN`/`ANALYZE`/`REINDEX`/`VACUUM`/`SAVEPOINT` 原生 SQL 支持（v0.5.1 补齐）
|
||||
- 🛡 **输入校验全覆盖** — `maxLength`/`min`/`max` 约束、类型检查、必填验证
|
||||
- 💾 **多引擎架构** — Memory / IndexedDB / OPFS / Hybrid(write-through) / Aria 五种模式
|
||||
- 📝 **完整 SQL 支持** — SELECT/JOIN/子查询/GROUP BY/HAVING/ORDER BY/LIMIT/BETWEEN/IF NOT EXISTS/ALTER TABLE/TRUNCATE TABLE/UNION/INSERT...SELECT/事务语句/CREATE INDEX/EXISTS（v0.3.0）+ CASE WHEN/哈希连接/组提交（v0.3.1）+ 多标签页同步（v0.3.2）
|
||||
@@ -31,7 +32,7 @@
|
||||
- 🌲 **RB-Tree 完整实现** — 标准红黑树插入+删除修复，O(log n) 保证
|
||||
- ⚡ **性能优化** — SSTableReader 二分查找统一、IndexedDB 索引利用、crypto 实例化避免全局状态
|
||||
- 🌐 **浏览器兼容** — Chrome 80+ / Firefox 80+ / Safari 14+ / Edge 80+ / Node.js 16+
|
||||
- 🧪 **1022 测试 · 86.7% 覆盖率** — 62 套件 + 7 个 Playwright 真实 Chromium e2e，生产级质量保证
|
||||
- 🧪 **1009 测试 · 87.3% 覆盖率** — 62 套件 + 7 个 Playwright 真实 Chromium e2e，生产级质量保证
|
||||
|
||||
---
|
||||
|
||||
@@ -308,7 +309,7 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
|
||||
| **查询性能** | ⚡ O(1) PK | 🟡 O(1) PK | 🟡 O(1) PK | ⚡ O(1) PK | ⚡ O(log n) |
|
||||
| **数据上限** | 内存限制 | ~2GB(IDB限制) | ~磁盘可用（页面化后大表可行） | ~2GB(IDB) | 内存限制 |
|
||||
| **浏览器** | 全部 | 全部 | Chrome/Edge 102+ / Firefox 111+ / Safari 15.2+ | 全部 | 全部 |
|
||||
| **多标签页** | — | ✅ | ❌（Web Locks 独占锁，v0.5.0） | ❌ | ✅ 锁保护 |
|
||||
| **多标签页** | — | ✅ versionchange | ❌ 无保护 | ❌ 无保护 | ✅ Web Locks 独占锁（v0.5.0） |
|
||||
| **全库加密** | — | — | — | — | ✅ AES-GCM（v0.5.0） |
|
||||
| **适用场景** | 缓存/测试 | 标准持久化 | Chromium+ 持久化 | 速度+持久化 | 大规模/分析 |
|
||||
| **测试覆盖** | 30+ | 30+ | 15+e2e | 15+ | 400+ |
|
||||
@@ -333,7 +334,7 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');
|
||||
|
||||
### Hybrid 模式
|
||||
- **环境**: 所有浏览器
|
||||
- **限制**: 磁盘引擎决定底层限制（IndexedDB ~2GB / OPFS Chrome only）
|
||||
- **限制**: 磁盘引擎决定底层限制（IndexedDB ~2GB / OPFS 需 OPFS 支持浏览器）
|
||||
- **能力**: write-through 双写（内存+磁盘）、提交顺序保证（磁盘优先）、读从内存
|
||||
- **适用**: 需要内存速度 + 磁盘持久化的混合场景
|
||||
|
||||
@@ -374,7 +375,7 @@ const rows = await db.query('SELECT * FROM users');
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ AriaEngine v0.5.0 │
|
||||
│ AriaEngine v0.5.1 │
|
||||
│ (implements IStorageEngine) │
|
||||
├──────────────────────────────────────────┤
|
||||
│ LSM-Tree │ Buffer Pool │ WAL │
|
||||
@@ -428,10 +429,10 @@ npm run typecheck # 类型检查
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 测试用例 | 1022 |
|
||||
| 测试用例 | 1009 |
|
||||
| 测试套件 | 62（+7 Playwright e2e） |
|
||||
| 行覆盖率 | 86.7% |
|
||||
| SQL 关键字 | 36 |
|
||||
| 行覆盖率 | 87.3% |
|
||||
| SQL 关键字 | 72 |
|
||||
| 存储引擎 | 5（Memory / IndexedDB / OPFS / Hybrid / **Aria**） |
|
||||
|
||||
### 🌐 浏览器兼容性
|
||||
@@ -462,7 +463,6 @@ src/
|
||||
├── core.ts # 主类
|
||||
├── constants.ts # 类型定义 + 配置 + DatabaseError
|
||||
├── connection-manager.ts # 连接池管理
|
||||
├── utils.ts # 工具函数
|
||||
├── engine/ # 存储引擎（Memory/IndexedDB/OPFS/Aria）
|
||||
├── hybrid/ # 混合引擎（write-through）
|
||||
├── table/ # 表管理 + Schema 校验
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>⚡ 性能基准 — MetonaSqlark v0.4.4</title>
|
||||
<title>⚡ 性能基准 — MetonaSqlark v0.5.1</title>
|
||||
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' rx='8' fill='%236366f1'/><text x='16' y='22' text-anchor='middle' font-size='20' fill='white'>◈</text></svg>">
|
||||
<style>
|
||||
:root {
|
||||
|
||||
+33
-8
@@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>🧪 在线演示 — MetonaSqlark v0.4.4</title>
|
||||
<title>🧪 在线演示 — MetonaSqlark v0.5.1</title>
|
||||
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' rx='8' fill='%236366f1'/><text x='16' y='22' text-anchor='middle' font-size='20' fill='white'>◈</text></svg>">
|
||||
<style>
|
||||
:root {
|
||||
@@ -84,7 +84,7 @@
|
||||
<a href="demo.html" class="nav-active">演示</a>
|
||||
<a href="benchmark.html">基准</a>
|
||||
</nav>
|
||||
<div class="status"><span class="dot" id="engine-dot"></span> <span id="engine-status">Memory</span> 模式 — v0.4.4</div>
|
||||
<div class="status"><span class="dot" id="engine-dot"></span> <span id="engine-status">Memory</span> 模式 — v0.5.1</div>
|
||||
<button class="btn btn-preset" onclick="switchEngine('memory')" id="btn-memory" style="margin:6px 4px 6px 0;padding:6px 12px;">⚡ Memory</button>
|
||||
<button class="btn btn-preset" onclick="switchEngine('aria')" id="btn-aria" style="margin:6px 0;padding:6px 12px;color:#ec4899;border-color:#ec4899;">🌲 Aria</button>
|
||||
</header>
|
||||
@@ -92,7 +92,7 @@
|
||||
<div class="main">
|
||||
<div class="editor-panel">
|
||||
<div class="editor-area">
|
||||
<textarea id="sql-input" placeholder="输入 SQL 语句... SELECT * FROM users; INSERT INTO users VALUES ('4', 'Diana', 'diana@test.com', 28); SELECT u.name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id;">-- 🚀 MetonaSqlark v0.4.4 在线演示
|
||||
<textarea id="sql-input" placeholder="输入 SQL 语句... SELECT * FROM users; INSERT INTO users VALUES ('4', 'Diana', 'diana@test.com', 28); SELECT u.name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id;">-- 🚀 MetonaSqlark v0.5.1 在线演示
|
||||
-- 已预置 users / orders / products 表数据
|
||||
-- 新特性: ALTER TABLE · TRUNCATE TABLE · WAL同步 · MVCC · SQL注入防护
|
||||
|
||||
@@ -134,6 +134,7 @@
|
||||
<button class="btn btn-preset" onclick="loadPreset('onupdate')" style="color:#fbbf24;border-color:#fbbf24;">🔄 ON UPDATE</button>
|
||||
<button class="btn btn-preset" onclick="loadPreset('repair')" style="color:#22c55e;border-color:#22c55e;">🛡 自愈</button>
|
||||
<button class="btn btn-preset" onclick="loadPreset('aria')" style="color:#ec4899;border-color:#ec4899;">🌲 Aria</button>
|
||||
<button class="btn btn-preset" onclick="loadPreset('maint')" style="color:#22c55e;border-color:#22c55e;">🛠 v0.5.1 维护语句</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -554,7 +555,7 @@ SELECT COUNT(*) as total FROM temp_logs;
|
||||
|
||||
-- 清理
|
||||
DROP TABLE temp_logs;`,
|
||||
aria: `-- 🌲 AriaEngine 演示 (v0.4.4)
|
||||
aria: `-- 🌲 AriaEngine 演示 (v0.5.1)
|
||||
-- 点击右上角「🌲 Aria」按钮切换数据库引擎到 AriaEngine
|
||||
-- 当前数据库即运行在 Aria 引擎上（LSM-Tree · WAL 崩溃恢复 · MVCC · BloomFilter）
|
||||
-- 基础 CRUD 与 Memory 引擎完全兼容
|
||||
@@ -589,18 +590,42 @@ DROP TABLE temp_logs;`,
|
||||
|
||||
-- AriaEngine 特性:
|
||||
-- • LSM-Tree: MemTable (红黑树) → SSTable 多级索引
|
||||
-- • WAL: 原子写入 + 崩溃恢复（残缺 SSTable 打开自动跳过）+ 批量组提交
|
||||
-- • WAL: 分片文件 + 标准 CRC32 + 空洞检测 + 崩溃恢复（残缺 SSTable 自动跳过）
|
||||
-- • MVCC: 版本链 + 快照隔离
|
||||
-- • Buffer Pool: SSTable LRU 缓存 (256页 ~ 1MB) ✅ 已生效
|
||||
-- • 页面化物理存储: SSTable 4KB 页面 + BufferPool LRU 缓存 (v0.5.0)
|
||||
-- • 完整性: 整文件 CRC-32 校验（数据腐坏自动清理自愈）
|
||||
-- • Bloom Filter: FNV-1a + Murmur 双哈希
|
||||
-- • 二级索引: 每列独立 LSM + 跨重启自动恢复
|
||||
-- • 外键级联: ON DELETE / ON UPDATE — CASCADE / SET NULL / RESTRICT (v0.4.2)
|
||||
-- • 自愈: db.repair() 无需删库重建 (v0.4.2)
|
||||
-- • 外键级联: ON DELETE / ON UPDATE — CASCADE / SET NULL / RESTRICT
|
||||
-- • 自愈: db.repair() 无需删库重建（含孤儿页面/残留清理）
|
||||
-- • 维护语句: EXPLAIN / ANALYZE / REINDEX / VACUUM / SAVEPOINT (v0.5.1)
|
||||
|
||||
-- 生产环境 API（与演示页右上角切换等价）
|
||||
-- const db = await MetonaSqlark.create({
|
||||
-- name: 'my-app', mode: 'aria'
|
||||
-- });`,
|
||||
maint: `-- 🛠 维护语句 (v0.5.1)
|
||||
-- EXPLAIN: 输出查询计划（任何引擎可用）
|
||||
EXPLAIN SELECT * FROM users WHERE age > 18;
|
||||
|
||||
-- ANALYZE: 收集表统计信息（仅 Aria 引擎）
|
||||
ANALYZE TABLE users;
|
||||
|
||||
-- REINDEX: 重建二级索引（仅 Aria 引擎）
|
||||
REINDEX TABLE users;
|
||||
|
||||
-- VACUUM: 压缩 LSM + 清理碎片（仅 Aria 引擎）
|
||||
VACUUM;
|
||||
|
||||
-- SAVEPOINT: 嵌套事务保存点（仅 Aria 引擎）
|
||||
BEGIN;
|
||||
UPDATE users SET age = age + 1 WHERE id = '1';
|
||||
SAVEPOINT sp1;
|
||||
UPDATE users SET age = 0 WHERE id = '1';
|
||||
ROLLBACK TO SAVEPOINT sp1;
|
||||
RELEASE SAVEPOINT sp1;
|
||||
COMMIT;
|
||||
SELECT id, age FROM users WHERE id = '1';`,
|
||||
casewhen: `-- 🎯 CASE WHEN 条件表达式 (v0.3.1 / v0.3.2)
|
||||
|
||||
-- SELECT 列：多 WHEN + ELSE
|
||||
|
||||
+33
-16
@@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>📖 API 文档 — MetonaSqlark v0.4.4</title>
|
||||
<title>📖 API 文档 — MetonaSqlark v0.5.1</title>
|
||||
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><rect width='32' height='32' rx='8' fill='%236366f1'/><text x='16' y='22' text-anchor='middle' font-size='20' fill='white'>◈</text></svg>">
|
||||
<style>
|
||||
:root {
|
||||
@@ -586,7 +586,7 @@ db.<span class="f">addMigration</span>(<span class="n">3</span>, <span class="k"
|
||||
<tr><td><code>beforeDropTable</code></td><td>删除表前</td><td>tableName</td></tr>
|
||||
<tr><td><code>afterDropTable</code></td><td>删除表后</td><td>tableName</td></tr>
|
||||
<tr><td><code>beforeInsert</code></td><td>插入前</td><td>rows[]</td></tr>
|
||||
<tr><td><code>afterInsert</code></td><td>插入后</td><td>rows[]</td></tr>
|
||||
<tr><td><code>afterInsert</code></td><td>插入后</td><td>rows[], pks</td></tr>
|
||||
<tr><td><code>beforeUpdate</code></td><td>更新前</td><td>query, updates</td></tr>
|
||||
<tr><td><code>afterUpdate</code></td><td>更新后</td><td>query, updates, count</td></tr>
|
||||
<tr><td><code>beforeDelete</code></td><td>删除前</td><td>query</td></tr>
|
||||
@@ -744,6 +744,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<tr><td><code>onError</code></td><td><code>(err) => void</code></td><td>-</td><td>错误回调（v0.2.5 接入执行路径）</td></tr>
|
||||
<tr><td><code>maxRowsPerQuery</code></td><td><code>number</code></td><td><code>0</code></td><td>查询结果行数上限（0=不限制）✅ v0.2.5 生效</td></tr>
|
||||
<tr><td><code>multiTabSync</code></td><td><code>boolean</code></td><td><code>false</code></td><td>多标签页同步：BroadcastChannel 广播表变更，其他标签页自动刷新 🆕 v0.3.2</td></tr>
|
||||
<tr><td><code>aria</code></td><td><code>AriaEngineConfig</code></td><td>-</td><td>AriaEngine 专属配置透传：walSyncMode / checkpointInterval / encryption / pageStorage / compression 等 🆕 v0.5.0</td></tr>
|
||||
</table>
|
||||
|
||||
<h2 id="engine">💾 存储引擎</h2>
|
||||
@@ -763,7 +764,9 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<strong>v0.3.2 表达式与并发</strong> — WAL full模式真正同步 · MVCC接入读写路径 · SSTableReader二分查找统一 · crypto实例化 · IndexedDB索引利用 · compactLevel public接口 · WAL大小阈值自动checkpoint · SQL注入防护 · ALTER TABLE · TRUNCATE TABLE · 多标签页同步 · IDB schema持久化。<br>
|
||||
<strong>v0.4.2 生产就绪与崩溃自愈</strong> — 残缺 SSTable 打开自动跳过（不删库）· WAL 记录与计数原子写入 + 按 key 扫描恢复 · 事务进行中 checkpoint 不截断 WAL · 二级索引跨重启自动恢复 · ALTER TABLE / 事务内 DDL 全引擎持久化 · ON UPDATE 外键级联（含更新主键）· OPFS schema 持久化（空表/索引完整保留）· `repair()` / `clearAll()` 统一自愈接口 · 迁移版本持久化到库内。<br>
|
||||
<strong>v0.4.3 关闭时序与后台任务加固</strong> — 后台 flush/compaction 不再使用 setTimeout 延迟（close 排空全部任务后才关闭存储，杜绝"backend 关闭后写存储/重开污染"）· 后台失败在 `flush()`/`close()` 显式报告（`ARIA_BACKGROUND_ERROR`，不静默吞错）· 预加载等待链稳定（修复 compaction 竞态跳块丢数据）· 事务提交先落 WAL 再合并快照（崩溃一致）· OPFS 写操作串行队列 + close 等待。<br>
|
||||
<strong>v0.4.4 SSTable 编码修复</strong> — 大段中文内容（如 300KB 笔记）写入 AriaEngine 不再崩溃：块大小估算改 UTF-8 字节精确计算（修复中文 3 字节 vs 1 码元导致的缓冲区低估越界）· 长度字段 u16 → u32（修复 >64KB value 截断）· 大 value 独立成块 · 格式 v2（"SSTC"）与 v1（"SSTB"）双格式兼容（旧库数据不丢）· 中文主键 / 大内容索引列同步支持 · 958 测试 52 套件。</p>
|
||||
<strong>v0.4.4 SSTable 编码修复</strong> — 大段中文内容（如 300KB 笔记）写入 AriaEngine 不再崩溃：块大小估算改 UTF-8 字节精确计算（修复中文 3 字节 vs 1 码元导致的缓冲区低估越界）· 长度字段 u16 → u32（修复 >64KB value 截断）· 大 value 独立成块 · 格式 v2（"SSTC"）与 v1（"SSTB"）双格式兼容（旧库数据不丢）· 中文主键 / 大内容索引列同步支持。<br>
|
||||
<strong>v0.5.0 存储后端生产级硬化</strong> — 真实 CRC-32 完整性校验（SSTable 整文件 + WAL 记录，旧文件兼容）· 全库 AES-256-GCM 透明加密（EncryptedBackend + PBKDF2 密钥派生 + 密码验证）· WAL 分片文件重构（真追加 + 空洞检测 + 旧格式迁移）· SSTable 4KB 页面化物理存储（BufferPool/FileManager 真实接入，meta 存 pageIds 兼容旧数据）· OPFS 后端 v2（append 真追加 / 写队列健壮性 / 残留清理）· Web Locks 多标签页独占锁（ARIA_LOCKED）· LZ4 v2 原始大小头 · Playwright 真实 Chromium e2e（7 用例）· DatabaseConfig.aria 配置透传。<br>
|
||||
<strong>v0.5.1 深度审查修复</strong> — 14 个生命周期钩子全部真实接线（此前 6 个 CRUD 钩子从未触发）· EXPLAIN / ANALYZE / REINDEX / VACUUM / SAVEPOINT SQL 入口补齐（此前仅有引擎方法无法触发）· db.backup() 公共方法 · 删除全部死代码（utils.ts 整文件 / MVCC 读侧 / estimateQueryCost 未接线优化器 / 40+ 统计辅助方法）· 1009 测试 62 套件 · 87.3% 行覆盖率。</p>
|
||||
|
||||
<h3>存储模式对比</h3>
|
||||
<table>
|
||||
@@ -772,38 +775,43 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<tr><td>事务</td><td>✅ 快照</td><td>✅ 原子</td><td>✅ 快照</td><td>✅ 双引擎</td><td>✅ MVCC</td></tr>
|
||||
<tr><td>索引</td><td>Hash</td><td>Hash</td><td>Hash</td><td>Hash</td><td>LSM二级</td></tr>
|
||||
<tr><td>上限</td><td>内存</td><td>~2GB</td><td>磁盘</td><td>~2GB</td><td>内存</td></tr>
|
||||
<tr><td>浏览器</td><td>全部</td><td>全部</td><td>Chromium</td><td>全部</td><td>全部</td></tr>
|
||||
<tr><td>浏览器</td><td>全部</td><td>全部</td><td>Chrome/Edge 102+ · Firefox 111+ · Safari 15.2+</td><td>全部</td><td>全部</td></tr>
|
||||
</table>
|
||||
|
||||
<h3>核心特性</h3>
|
||||
<table>
|
||||
<tr><th>特性</th><th>说明</th></tr>
|
||||
<tr><td><strong>LSM-Tree 索引</strong></td><td>MemTable (红黑树) + 多级 SSTable，写优化，支持范围扫描</td></tr>
|
||||
<tr><td><strong>Slotted Page 格式</strong></td><td>4KB 固定页面，Slot Directory + Tuple 二进制序列化</td></tr>
|
||||
<tr><td><strong>Buffer Pool</strong></td><td>LRU 页面缓存，可控内存占用（默认 256 页 ≈ 1MB）</td></tr>
|
||||
<tr><td><strong>WAL 日志</strong></td><td>Write-Ahead Log 保证崩溃恢复，支持 full/batch/none 三种同步模式（full 模式真正同步 ✅ v0.2.5），16MB 阈值自动 checkpoint</td></tr>
|
||||
<tr><td><strong>MVCC 事务</strong></td><td>快照隔离 (Snapshot Isolation)，读写不互斥，版本链 + GC，读写路径接入版本链 ✅ v0.2.5</td></tr>
|
||||
<tr><td><strong>4KB 页面化物理存储</strong></td><td>SSTable 切分为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），save 即落盘，`SSTableMeta.pageIds` 持久化（旧整 value 数据兼容）✅ v0.5.0</td></tr>
|
||||
<tr><td><strong>Buffer Pool</strong></td><td>LRU 页面缓存，可控内存占用（默认 256 页 ≈ 1MB），脏页写回 ✅ v0.5.0 真实接入</td></tr>
|
||||
<tr><td><strong>WAL 日志</strong></td><td>分片文件（`__wal_%06d.bin`，4MB 阈值切换 + 真追加）· 标准 CRC32 记录校验 · full/batch/none 三种同步模式（full 真正同步）· 空洞检测截断 · 16MB 阈值自动 checkpoint ✅ v0.5.0</td></tr>
|
||||
<tr><td><strong>MVCC 事务</strong></td><td>快照隔离 (Snapshot Isolation)，读写不互斥，版本链 + GC（引擎事务读取走 txnSnapshot，MVCC 版本链作 undo log）</td></tr>
|
||||
<tr><td><strong>全库 AES-GCM 加密</strong></td><td>EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）· PBKDF2 密钥派生 + salt 持久化 + 密码验证 · 明文/加密库开关一致性检测 ✅ v0.5.0</td></tr>
|
||||
<tr><td><strong>多标签页独占锁</strong></td><td>Web Locks API：第二个标签页打开同一库抛 `ARIA_LOCKED`，open 失败自动释放 ✅ v0.5.0</td></tr>
|
||||
<tr><td><strong>Bloom Filter</strong></td><td>快速判定 key 不存在，减少无效磁盘 I/O，SSTableReader 二分查找统一 ✅ v0.2.5</td></tr>
|
||||
<tr><td><strong>LZ4 压缩</strong></td><td>可选页面级压缩，空间效率提升</td></tr>
|
||||
<tr><td><strong>LZ4 压缩（v2）</strong></td><td>SSTable 级压缩，压缩流自带原始大小头（高压缩率不截断）✅ v0.5.0</td></tr>
|
||||
</table>
|
||||
|
||||
<h3>使用方式</h3>
|
||||
<pre><span class="c">// 激活 AriaEngine</span>
|
||||
<pre><span class="c">// 激活 AriaEngine（OPFS 后端默认页面化存储）</span>
|
||||
<span class="k">const</span> db = <span class="k">await</span> <span class="f">MetonaSqlark.create</span>({
|
||||
<span class="s">name</span>: <span class="s">'my-app'</span>,
|
||||
<span class="s">mode</span>: <span class="s">'aria'</span>, <span class="c">// 🆕 AriaEngine 模式</span>
|
||||
<span class="s">diskEngine</span>: <span class="s">'indexeddb'</span>, <span class="c">// 底层存储后端（indexeddb | opfs | memory）</span>
|
||||
<span class="s">diskEngine</span>: <span class="s">'opfs'</span>, <span class="c">// 底层存储后端（indexeddb | opfs | memory）</span>
|
||||
<span class="s">aria</span>: { <span class="c">// AriaEngine 专属配置透传 🆕 v0.5.0</span>
|
||||
<span class="s">walSyncMode</span>: <span class="s">'full'</span>, <span class="c">// WAL 同步模式</span>
|
||||
<span class="s">encryption</span>: { <span class="s">password</span>: <span class="s">'my-password'</span> }, <span class="c">// 全库 AES-GCM 加密 🆕 v0.5.0</span>
|
||||
},
|
||||
});
|
||||
|
||||
<span class="c">// 或直接实例化 — 支持细粒度配置</span>
|
||||
<span class="k">import</span> { <span class="t">AriaEngine</span> } <span class="k">from</span> <span class="s">'@metona-team/metona-sqlark'</span>;
|
||||
<span class="k">const</span> engine = <span class="k">new</span> <span class="f">AriaEngine</span>({
|
||||
<span class="s">pageSize</span>: <span class="n">4096</span>, <span class="c">// 页面大小</span>
|
||||
<span class="s">bufferPoolPages</span>: <span class="n">256</span>, <span class="c">// 缓存页数</span>
|
||||
<span class="s">bufferPoolPages</span>: <span class="n">256</span>, <span class="c">// Buffer Pool 页面数量</span>
|
||||
<span class="s">memtableSizeThreshold</span>: <span class="n">4194304</span>, <span class="c">// MemTable 刷盘阈值 4MB</span>
|
||||
<span class="s">walEnabled</span>: <span class="k">true</span>, <span class="c">// 启用 WAL</span>
|
||||
<span class="s">walSyncMode</span>: <span class="s">'batch'</span>, <span class="c">// 'full' | 'batch' | 'none'</span>
|
||||
<span class="s">walSyncMode</span>: <span class="s">'full'</span>, <span class="c">// 'full' | 'batch' | 'none'（默认 full）</span>
|
||||
<span class="s">storageBackend</span>: <span class="s">'indexeddb'</span>, <span class="c">// 存储后端</span>
|
||||
<span class="s">encryption</span>: { <span class="s">password</span>: <span class="s">'my-password'</span> }, <span class="c">// 全库加密</span>
|
||||
});</pre>
|
||||
|
||||
<h3>AriaEngine 配置项</h3>
|
||||
@@ -815,11 +823,13 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<tr><td><code>levelSizeMultiplier</code></td><td><code>number</code></td><td><code>10</code></td><td>LSM 层级容量倍数</td></tr>
|
||||
<tr><td><code>bloomFilterBitsPerKey</code></td><td><code>number</code></td><td><code>10</code></td><td>Bloom Filter 每 key 位数</td></tr>
|
||||
<tr><td><code>walEnabled</code></td><td><code>boolean</code></td><td><code>true</code></td><td>是否启用 WAL</td></tr>
|
||||
<tr><td><code>walSyncMode</code></td><td><code>'full'|'batch'|'none'</code></td><td><code>'batch'</code></td><td>WAL 同步策略（full 模式真正同步 ✅ v0.2.5）</td></tr>
|
||||
<tr><td><code>walSyncMode</code></td><td><code>'full'|'batch'|'none'</code></td><td><code>'full'</code></td><td>WAL 同步策略（full 真正同步 ✅ v0.2.4 起默认 full）</td></tr>
|
||||
<tr><td><code>checkpointInterval</code></td><td><code>number</code></td><td><code>1000</code></td><td>Checkpoint 触发间隔（操作数）</td></tr>
|
||||
<tr><td><code>walSizeThreshold</code></td><td><code>number</code></td><td><code>16777216</code></td><td>WAL 大小阈值（字节），超阈值触发 checkpoint ✅ v0.2.5</td></tr>
|
||||
<tr><td><code>compression</code></td><td><code>boolean</code></td><td><code>false</code></td><td>是否启用页面压缩</td></tr>
|
||||
<tr><td><code>storageBackend</code></td><td><code>'indexeddb'|'opfs'|'memory'</code></td><td><code>'indexeddb'</code></td><td>存储后端类型</td></tr>
|
||||
<tr><td><code>encryption</code></td><td><code>{ password: string }</code></td><td>-</td><td>全库 AES-256-GCM 透明加密（PBKDF2 派生 + salt 持久化 + 密码验证）🆕 v0.5.0</td></tr>
|
||||
<tr><td><code>pageStorage</code></td><td><code>boolean</code></td><td>OPFS 自动启用</td><td>SSTable 4KB 页面化物理存储（BufferPool 缓存）🆕 v0.5.0</td></tr>
|
||||
</table>
|
||||
|
||||
<h2 id="errors">⚠️ 错误处理</h2>
|
||||
@@ -849,6 +859,13 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<tr><td><code>TRANSACTION_ERROR</code></td><td>事务执行失败</td></tr>
|
||||
<tr><td><code>COMPILE_ERROR</code></td><td>编译 AST 到查询计划失败</td></tr>
|
||||
<tr><td><code>CONFIG_ERROR</code></td><td>配置错误</td></tr>
|
||||
<tr><td><code>ARIA_LOCKED</code></td><td>数据库已被其他标签页打开（Web Locks 独占锁）🆕 v0.5.0</td></tr>
|
||||
<tr><td><code>ARIA_DECRYPT_ERROR</code></td><td>解密失败：密码错误 / 密钥元数据损坏 / 数据被篡改 🆕 v0.5.0</td></tr>
|
||||
<tr><td><code>ARIA_ENCRYPT_REQUIRED</code></td><td>库已加密但未提供密码 🆕 v0.5.0</td></tr>
|
||||
<tr><td><code>ARIA_ENCRYPT_CONFIG_ERROR</code></td><td>明文库无法以加密模式打开 / 空密码 🆕 v0.5.0</td></tr>
|
||||
<tr><td><code>ARIA_BACKGROUND_ERROR</code></td><td>后台 flush/compaction 失败（flush/close 时显式报告）</td></tr>
|
||||
<tr><td><code>SAVEPOINT_EXISTS</code> / <code>SAVEPOINT_NOT_FOUND</code></td><td>保存点已存在 / 回滚到不存在的保存点 🆕 v0.5.1 SQL 入口</td></tr>
|
||||
<tr><td><code>NOT_SUPPORTED</code></td><td>引擎不支持的操作（如 Memory 引擎执行 ANALYZE / VACUUM / SAVEPOINT）🆕 v0.5.1</td></tr>
|
||||
</table>
|
||||
|
||||
</main>
|
||||
|
||||
+20
-10
@@ -153,7 +153,7 @@
|
||||
<!-- Hero -->
|
||||
<section class="hero">
|
||||
<div class="container">
|
||||
<div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.4.4 SSTable 编码修复 — 958测试 52套件 · 大内容（300KB中文）不再崩溃 · u32长度字段 · 双格式兼容 · 零回归</div>
|
||||
<div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.5.1 存储后端生产级硬化 — 1009测试 62套件 · 全库 AES-GCM 加密 · WAL 分片 · SSTable 页面化 · 多标签页锁 · 真实 Chromium e2e</div>
|
||||
<h1>前端的 <span class="gradient-text">SQL 数据库</span></h1>
|
||||
<p>TypeScript 原生构建，5 种存储引擎，支持完整 SQL 查询。<br>零运行时依赖，开箱即用。AriaEngine 自研引擎：LSM-Tree + WAL 同步 + MVCC。</p>
|
||||
<div class="actions">
|
||||
@@ -243,8 +243,8 @@ npm install @metona-team/metona-sqlark
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🌲</div>
|
||||
<h3>AriaEngine <span style="font-size:0.65rem;color:var(--accent);vertical-align:super;">v0.4.4</span></h3>
|
||||
<p>自研 LSM-Tree 页面式存储引擎。MemTable 红黑树 + 多级 SSTable、Bloom Filter 快速判存、WAL 原子写入 full模式真正同步、MVCC 快照隔离、崩溃恢复自动跳过残缺 SSTable、二级索引跨重启恢复、ON UPDATE/DELETE 外键级联。</p>
|
||||
<h3>AriaEngine <span style="font-size:0.65rem;color:var(--accent);vertical-align:super;">v0.5.1</span></h3>
|
||||
<p>自研 LSM-Tree 存储引擎：SSTable 4KB 页面化物理存储（BufferPool LRU）、WAL 分片文件原子写入、全库 AES-GCM 透明加密、标准 CRC-32 完整性校验、MVCC 快照隔离、二级索引跨重启恢复、ON UPDATE/DELETE 外键级联、崩溃恢复自愈。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🔒</div>
|
||||
@@ -264,7 +264,7 @@ npm install @metona-team/metona-sqlark
|
||||
<div class="feature-card">
|
||||
<div class="icon">🛡</div>
|
||||
<h3>崩溃恢复自愈</h3>
|
||||
<p>异常退出后无需删库重建：打开自动跳过残缺 SSTable，db.repair() 清理损坏数据并重建索引，db.clearAll() 重置。迁移版本持久化，重启不重跑。</p>
|
||||
<p>异常退出后无需删库重建：整文件 CRC-32 校验 + 打开自动跳过损坏 SSTable，db.repair() 清理损坏数据/孤儿页面/残留文件并重建索引，db.clearAll() 重置。迁移版本持久化，重启不重跑。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🏊</div>
|
||||
@@ -274,7 +274,7 @@ npm install @metona-team/metona-sqlark
|
||||
<div class="feature-card">
|
||||
<div class="icon">🧩</div>
|
||||
<h3>插件系统</h3>
|
||||
<p>14 种生命周期钩子：beforeCreateTable / afterInsert / beforeQuery / afterTransaction……按优先级注册。</p>
|
||||
<p>14 种生命周期钩子全部真实触发（Table API 与 SQL 双路径）：beforeCreateTable / afterInsert / beforeQuery / afterTransaction……按优先级注册。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">📦</div>
|
||||
@@ -286,10 +286,20 @@ npm install @metona-team/metona-sqlark
|
||||
<h3>聚合 & 分组</h3>
|
||||
<p>COUNT / SUM / AVG / MIN / MAX 五大聚合函数，GROUP BY + HAVING 子句，DISTINCT 去重。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🔐</div>
|
||||
<h3>全库加密 + 多标签页锁</h3>
|
||||
<p>encryption.password 一键启用 AES-256-GCM 全库透明加密（密码验证 + 篡改检测）。Web Locks 独占锁：第二个标签页打开同一库抛 ARIA_LOCKED。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🛠</div>
|
||||
<h3>维护语句（SQL）</h3>
|
||||
<p>EXPLAIN 查询计划 · ANALYZE 表统计 · REINDEX 重建索引 · VACUUM 压缩 · SAVEPOINT 嵌套事务保存点 — 全部原生 SQL 语法。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">🔄</div>
|
||||
<h3>数据迁移</h3>
|
||||
<p>内置版本迁移系统，addMigration + migrateTo API。导入导出支持单表/全库 JSON 序列化。</p>
|
||||
<p>内置版本迁移系统，addMigration + migrateTo API。导入导出支持单表/全库 JSON 序列化，db.backup() 在线一致性备份。</p>
|
||||
</div>
|
||||
<div class="feature-card">
|
||||
<div class="icon">📡</div>
|
||||
@@ -404,12 +414,12 @@ npm install @metona-team/metona-sqlark
|
||||
<p>MetonaSqlark 的核心指标</p>
|
||||
</div>
|
||||
<div class="stats">
|
||||
<div class="stat-card"><div class="num">958</div><div class="label">测试用例</div></div>
|
||||
<div class="stat-card"><div class="num">84.2%</div><div class="label">行覆盖率</div></div>
|
||||
<div class="stat-card"><div class="num">1009</div><div class="label">测试用例</div></div>
|
||||
<div class="stat-card"><div class="num">87.3%</div><div class="label">行覆盖率</div></div>
|
||||
<div class="stat-card"><div class="num">~27KB</div><div class="label">gzip 体积</div></div>
|
||||
<div class="stat-card"><div class="num">5</div><div class="label">存储引擎</div></div>
|
||||
<div class="stat-card"><div class="num">36</div><div class="label">SQL 关键字</div></div>
|
||||
<div class="stat-card"><div class="num">51</div><div class="label">测试套件</div></div>
|
||||
<div class="stat-card"><div class="num">72</div><div class="label">SQL 关键字</div></div>
|
||||
<div class="stat-card"><div class="num">62</div><div class="label">测试套件</div></div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
Reference in New Issue
Block a user