docs: v0.2.4 五模式对比表 + 环境限制/能力详细说明 + 701测试

2026-07-27 22:22:28 +08:00
parent 4c789a5ac3
commit b6619e8719
5 changed files with 56 additions and 12 deletions
@@ -4,7 +4,7 @@
  <img src="https://img.shields.io/badge/version-0.2.2-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-91.0%25-brightgreen?style=flat-square" alt="coverage">
-  <img src="https://img.shields.io/badge/tests-543%20passed-success?style=flat-square" alt="tests">
+  <img src="https://img.shields.io/badge/tests-701%20passed-success?style=flat-square" alt="tests">
 </p>

 > 基于 TypeScript 的**前端关系型数据库**，支持完整 SQL 查询、Query Builder 链式 API、与 **AriaEngine 自研页面式存储引擎**。
@@ -225,6 +225,51 @@ const { data, loading, refresh } = useSqlarkQuery(db, 'SELECT * FROM users');

 ---

+## 📊 存储模式对比
+
+| 特性 | Memory | Disk (IndexedDB) | Disk (OPFS) | Hybrid | Aria |
+|------|--------|------------------|-------------|--------|------|
+| **持久化** | ❌ 重启丢失 | ✅ IndexedDB | ✅ OPFS文件系统 | ✅ 内存+磁盘 | ✅ 后端决定 |
+| **事务回滚** | ✅ 快照 | ✅ 原子flush | ✅ 快照 | ✅ 双引擎 | ✅ MVCC |
+| **二级索引** | ✅ Hash | ✅ Hash | ✅ Hash | ✅ Hash | ✅ LSM |
+| **查询性能** | ⚡ O(1) PK | 🟡 O(1) PK | 🟡 O(1) PK | ⚡ O(1) PK | ⚡ O(log n) |
+| **数据上限** | 内存限制 | ~2GB(IDB限制) | ~磁盘可用 | ~2GB(IDB) | 内存限制 |
+| **浏览器** | 全部 | 全部 | Chrome/Edge 102+ | 全部 | 全部 |
+| **适用场景** | 缓存/测试 | 标准持久化 | Chromium专有 | 速度+持久化 | 大规模/分析 |
+| **测试覆盖** | 30+ | 30+ | 12 | 15+ | 200+ |
+
+### Memory 模式
+- **环境**: 所有浏览器、Node.js
+- **限制**: 数据不持久化，页面刷新/进程重启后数据丢失
+- **能力**: 完整 CRUD、事务回滚、外键级联、二级索引、SQL 全支持
+- **适用**: 临时数据、单元测试、缓存层
+
+### Disk (IndexedDB) 模式
+- **环境**: 所有现代浏览器（Chrome/Firefox/Safari/Edge）、Node.js（fake-indexeddb）
+- **限制**: 受浏览器 IndexedDB 配额限制（通常 ~2GB），多标签页需处理版本冲突
+- **能力**: 完整 CRUD、事务原子性（单 IDB 事务包裹）、外键级联、onversionchange 感知
+- **适用**: 标准前端数据库持久化场景
+
+### Disk (OPFS) 模式
+- **环境**: **仅限** Chrome 102+ / Edge 102+（Origin Private File System）
+- **限制**: Firefox/Safari 不支持 OPFS API；每次写入重写整表 JSON 文件（大表性能差，不建议 >1000 行）
+- **能力**: 完整 CRUD、重启自动加载数据、事务回滚
+- **适用**: Chromium 独占场景、小数据集持久化
+
+### Hybrid 模式
+- **环境**: 所有浏览器
+- **限制**: 磁盘引擎决定底层限制（IndexedDB ~2GB / OPFS Chrome only）
+- **能力**: write-through 双写（内存+磁盘）、提交顺序保证（磁盘优先）、读从内存
+- **适用**: 需要内存速度 + 磁盘持久化的混合场景
+
+### Aria 模式
+- **环境**: 所有浏览器（后端可选 IndexedDB / OPFS / Memory）
+- **限制**: Memory 后端重启丢失；IndexedDB 后端受配额限制；OPFS 后端仅 Chromium
+- **能力**: LSM-Tree 存储引擎、二级索引、MVCC 事务、WAL 崩溃恢复、Bloom Filter、AES-GCM 加密、Savepoint、EXPLAIN、ANALYZE、REINDEX、VACUUM
+- **适用**: 大规模数据分析、需要自研引擎可控性的高级场景
+
+---
+
 ## 🌲 AriaEngine — 自研存储引擎 (v0.2.0)

 AriaEngine 是内置的页面式存储引擎，对标 SQLite 的设计理念：
@@ -294,7 +339,7 @@ npm run typecheck # 类型检查

 | 指标 | 数值 |
 |------|------|
-| 测试用例 | 543 |
+| 测试用例 | 701 |
 | 测试套件 | 27 |
 | 行覆盖率 | 91.0% |
 | SQL 关键字 | 33 |
@@ -1,6 +1,6 @@
 {
  "name": "@metona-team/metona-sqlark",
-  "version": "0.2.5",
+  "version": "0.2.4",
  "description": "Frontend SQL database with in-memory and disk dual-mode storage",
  "type": "module",
  "main": "dist/metona-sqlark.js",
@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>🧪 在线演示 — MetonaSqlark v0.2.5</title>
+<title>🧪 在线演示 — MetonaSqlark v0.2.4</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 {
@@ -83,13 +83,13 @@
    <a href="docs.html">文档</a>
    <a href="demo.html" class="nav-active">演示</a>
  </nav>
-  <div class="status"><span class="dot"></span> Memory 模式 — v0.2.5</div>
+  <div class="status"><span class="dot"></span> Memory 模式 — v0.2.4</div>
 </header>

 <div class="main">
  <div class="editor-panel">
    <div class="editor-area">
-<textarea id="sql-input" placeholder="输入 SQL 语句...&#10;&#10;SELECT * FROM users;&#10;INSERT INTO users VALUES ('4', 'Diana', 'diana@test.com', 28);&#10;SELECT u.name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id;">-- 🚀 MetonaSqlark v0.2.5 在线演示
+<textarea id="sql-input" placeholder="输入 SQL 语句...&#10;&#10;SELECT * FROM users;&#10;INSERT INTO users VALUES ('4', 'Diana', 'diana@test.com', 28);&#10;SELECT u.name, o.amount FROM users u INNER JOIN orders o ON u.id = o.user_id;">-- 🚀 MetonaSqlark v0.2.4 在线演示
 	-- 已预置 users / orders / products 表数据
 	-- 新特性: AriaEngine · LSM-Tree · WAL · MVCC
 	
@@ -469,7 +469,7 @@ LIMIT 5 OFFSET 0;
 -- NOT LIKE 模糊排除
 	SELECT * FROM users
 	WHERE name NOT LIKE 'A%' AND age > 20;`,
-	  aria: `-- 🌲 AriaEngine 演示 (v0.2.5)
+	  aria: `-- 🌲 AriaEngine 演示 (v0.2.4)
 	-- AriaEngine: LSM-Tree 自研存储引擎
 	-- 支持 WAL 崩溃恢复 + MVCC 快照隔离
 	
@@ -522,7 +522,7 @@ document.addEventListener('keydown', e => {

 	// Boot
 	initDB().then(() => {
-	  console.log('✅ MetonaSqlark v0.2.5 demo ready');
+	  console.log('✅ MetonaSqlark v0.2.4 demo ready');
 	  setTimeout(runQuery, 300);
 	}).catch(err => {
 	  renderError('初始化失败: ' + err.message);
@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>📖 API 文档 — MetonaSqlark v0.2.5</title>
+<title>📖 API 文档 — MetonaSqlark v0.2.4</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 {
@@ -629,8 +629,7 @@ db.<span class="f">emit</span>(<span class="s">'users'</span>, { <span class="s"

 	<h2 id="aria-engine">🌲 AriaEngine 自研存储引擎</h2>
 	<p><strong>v0.2.0 新增</strong> — AriaEngine 是专为 MetonaSqlark 设计的页面式存储引擎，对标 SQLite 设计理念。<br>
-<strong>v0.2.2 OPFS 自研后端</strong> — 新增 OPFSBackend，纯浏览器文件系统，零 IndexedDB 依赖。<br>
-<strong>v0.2.5 引擎加固</strong> — RB-Tree 完整删除修复、LSM SSTable 缓存预热、LZ4 往返正确性。</p>
+<strong>v0.2.4 生产级</strong> — 二级索引 · MVCC事务 · BloomFilter · WAL全同步 · AES-GCM加密 · Savepoint · EXPLAIN · ANALYZE · REINDEX · VACUUM · BufferPool · 701测试全覆盖。</p>

 	<h3>核心特性</h3>
 	<table>
@@ -152,7 +152,7 @@
 <!-- Hero -->
 <section class="hero">
  <div class="container">
-<div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.2.5 生产级 — 二级索引 · MVCC接入 · BloomFilter · WAL全同步 · 内存预算</div>
+<div class="badge" style="margin-bottom:24px;"><span class="dot"></span> v0.2.4 生产级 — 二级索引 · MVCC接入 · BloomFilter · WAL全同步 · 内存预算</div>
 	    <h1>前端的 <span class="gradient-text">SQL 数据库</span></h1>
 	    <p>TypeScript 原生构建，5 种存储引擎，支持完整 SQL 查询。<br>零运行时依赖，开箱即用。AriaEngine 自研引擎：LSM-Tree + WAL + MVCC。</p>
    <div class="actions">