chore: 升级 metona-editor 0.4.1

2026-08-09 20:34:53 +08:00
parent c647b7e602
commit 6450cd6435
3 changed files with 88 additions and 25 deletions
@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>🧪 在线演示 — MetonaSqlark v0.4.1</title>
+<title>🧪 在线演示 — MetonaSqlark v0.4.3</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.1</div>
+  <div class="status"><span class="dot" id="engine-dot"></span> <span id="engine-status">Memory</span> 模式 — v0.4.3</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 语句...&#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.4.1 在线演示
+<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.4.3 在线演示
 	-- 已预置 users / orders / products 表数据
 	-- 新特性: ALTER TABLE · TRUNCATE TABLE · WAL同步 · MVCC · SQL注入防护
 	
@@ -131,6 +131,8 @@
        <button class="btn btn-preset" onclick="loadPreset('index')">🗂 索引</button>
        <button class="btn btn-preset" onclick="loadPreset('multistmt')">📜 多语句/事务</button>
        <button class="btn btn-preset" onclick="loadPreset('v040')" style="color:#22c55e;border-color:#22c55e;">🚰 v0.4.0 新特性</button>
+        <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>
      </div>
    </div>
@@ -174,7 +176,7 @@ async function initDB() {
    db = new DBClass({ name: 'demo', mode: engine });
    await db.init();

-    // v0.4.1: Aria 引擎持久化 — 每次加载清空上次演示数据，保证演示确定性
+    // v0.4.2: Aria 引擎持久化 — 每次加载清空上次演示数据，保证演示确定性
    if (engine === 'aria' && typeof db.getEngine().clearAll === 'function') {
      await db.getEngine().clearAll();
    }
@@ -230,7 +232,7 @@ async function seedDemoData(db) {
  ]);
 }

-// v0.4.1: 切换存储引擎（重建数据库实例）
+// v0.4.2: 切换存储引擎（重建数据库实例）
 async function switchEngine(engine) {
  if (engine === currentEngine) return;
  currentEngine = engine;
@@ -552,7 +554,7 @@ SELECT COUNT(*) as total FROM temp_logs;

 -- 清理
 DROP TABLE temp_logs;`,
-	  aria: `-- 🌲 AriaEngine 演示 (v0.4.1)
+	  aria: `-- 🌲 AriaEngine 演示 (v0.4.3)
 	-- 点击右上角「🌲 Aria」按钮切换数据库引擎到 AriaEngine
 	-- 当前数据库即运行在 Aria 引擎上（LSM-Tree · WAL 崩溃恢复 · MVCC · BloomFilter）
 	-- 基础 CRUD 与 Memory 引擎完全兼容
@@ -587,12 +589,13 @@ DROP TABLE temp_logs;`,
 	
 	-- AriaEngine 特性:
 	-- • LSM-Tree: MemTable (红黑树) → SSTable 多级索引
-	-- • WAL: Write-Ahead Log 保证崩溃恢复 + 批量组提交
+	-- • WAL: 原子写入 + 崩溃恢复（残缺 SSTable 打开自动跳过）+ 批量组提交
 	-- • MVCC: 版本链 + 快照隔离
 	-- • Buffer Pool: SSTable LRU 缓存 (256页 ~ 1MB) ✅ 已生效
 	-- • Bloom Filter: FNV-1a + Murmur 双哈希
-	-- • 二级索引: 每列独立 LSM + 动态 CREATE INDEX
-	-- • 外键级联: CASCADE / SET NULL / RESTRICT (v0.4.1)
+	-- • 二级索引: 每列独立 LSM + 跨重启自动恢复
+	-- • 外键级联: ON DELETE / ON UPDATE — CASCADE / SET NULL / RESTRICT (v0.4.2)
+	-- • 自愈: db.repair() 无需删库重建 (v0.4.2)
 	
 	-- 生产环境 API（与演示页右上角切换等价）
 	-- const db = await MetonaSqlark.create({
@@ -674,19 +677,64 @@ WHERE EXISTS (SELECT 1 FROM orders o2 WHERE o2.user_id = u.id AND o2.amount > 10
 -- 为 orders.user_id 创建索引（已有数据自动回填）
 CREATE INDEX idx_orders_user ON orders (user_id);

-- 索引查找（v0.4.1: JOIN 主表 WHERE 条件下推到引擎，真正走二级索引）
-SELECT u.name, o.product, o.amount
-FROM orders o JOIN users u ON u.id = o.user_id
-WHERE o.user_id = '1';
+  -- 索引查找（v0.4.2: JOIN 主表 WHERE 条件下推 + 二级索引跨重启恢复）
+  SELECT u.name, o.product, o.amount
+  FROM orders o JOIN users u ON u.id = o.user_id
+  WHERE o.user_id = '1';

-- 删除索引
-DROP INDEX idx_orders_user ON orders (user_id);
+  -- 删除索引
+  DROP INDEX idx_orders_user ON orders (user_id);

-- 删除后回退全表扫描（结果不变）
-SELECT * FROM orders WHERE user_id = '3';
+  -- 删除后回退全表扫描（结果不变）
+  SELECT * FROM orders WHERE user_id = '3';

-- DROP 不存在的索引会报错（INDEX_NOT_FOUND）
-- DROP INDEX idx_nonexist ON orders (user_id);`,
+  -- DROP 不存在的索引会报错（INDEX_NOT_FOUND）
+  -- DROP INDEX idx_nonexist ON orders (user_id);`,
+  onupdate: `-- 🔄 ON UPDATE 外键级联 (v0.4.2)
+  -- 更新父表主键 → 子表外键自动级联（CASCADE / SET NULL / RESTRICT）
+
+  -- 建带 onUpdate 外键的表
+  DROP TABLE IF EXISTS accounts;
+  DROP TABLE IF EXISTS audit_log;
+  CREATE TABLE accounts (id STRING PRIMARY KEY, owner STRING);
+  CREATE TABLE audit_log (
+    id STRING PRIMARY KEY,
+    account_id STRING REFERENCES accounts.id ON UPDATE CASCADE
+  );
+
+  -- 种子数据
+  INSERT INTO accounts VALUES ('a1', 'Alice');
+  INSERT INTO audit_log VALUES ('l1', 'a1');
+  INSERT INTO audit_log VALUES ('l2', 'a1');
+
+  -- 更新父表主键 a1 → a2
+  UPDATE accounts SET id = 'a2' WHERE id = 'a1';
+
+  -- 子表外键已级联为 a2
+  SELECT * FROM audit_log ORDER BY id;
+
+  -- 再按新主键反查
+  SELECT * FROM accounts WHERE id = 'a2';`,
+  repair: `-- 🛡 崩溃恢复自愈 (v0.4.2)
+  -- db.repair(): 校验并清理损坏 SSTable / 重建二级索引 / 截断 WAL
+  -- db.clearAll(): 清空全部数据与表结构（保留库本身）
+  -- 打开数据库时自动跳过残缺 SSTable，无需删库重建
+
+  -- 数据写入
+  CREATE TABLE IF NOT EXISTS notes (id STRING PRIMARY KEY, body STRING);
+  INSERT INTO notes VALUES ('n1', 'Hello');
+  INSERT INTO notes VALUES ('n2', 'World');
+
+  -- 模拟数据（正常数据）
+  SELECT * FROM notes ORDER BY id;
+
+  -- API 自愈（控制台执行）:
+  -- await db.repair();      → 校验+清理损坏文件，重建索引
+  -- await db.clearAll();    → 清空全部表与数据
+
+  -- 迁移版本持久化（重启后不重跑已执行迁移）
+  -- db.addMigration(1, async () => { ... });
+  -- await db.migrateTo(1);`,
 	multistmt: `-- 📜 多语句 + 事务语句 (v0.3.0)

 -- 分号分隔的多语句一次执行
@@ -753,7 +801,7 @@ document.addEventListener('keydown', e => {
 	document.getElementById('btn-aria').style.opacity = '0.6';
 	document.getElementById('engine-status').textContent = '⚡ Memory';
 	initDB().then(() => {
-	  console.log('✅ MetonaSqlark v0.4.1 demo ready');
+	  console.log('✅ MetonaSqlark v0.4.2 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.4.1</title>
+<title>📖 API 文档 — MetonaSqlark v0.4.3</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 {
@@ -95,6 +95,7 @@
    <a href="#foreign-key">外键级联</a>
    <a href="#connection-pool">连接池</a>
    <a href="#migration">数据迁移</a>
+    <a href="#selfheal">崩溃自愈 🆕</a>
    <a href="#export">导入导出</a>
    <a href="#plugin">插件 & 钩子</a>
    <a href="#subscribe">发布订阅</a>
@@ -197,8 +198,8 @@ db.<span class="f">isReady</span>();  <span class="c">// true</span>
  <tr><td><code>maxLength</code></td><td><code>number</code></td><td>字符串最大长度</td></tr>
  <tr><td><code>min</code>/<code>max</code></td><td><code>number</code></td><td>数值范围</td></tr>
  <tr><td><code>references</code></td><td><code>string</code></td><td>外键引用 <code>'table.column'</code></td></tr>
-  <tr><td><code>onDelete</code></td><td><code>'CASCADE'\|'SET NULL'\|'RESTRICT'</code></td><td>删除级联 🆕</td></tr>
-  <tr><td><code>onUpdate</code></td><td><code>'CASCADE'\|'SET NULL'\|'RESTRICT'</code></td><td>更新级联 🆕</td></tr>
+  <tr><td><code>onDelete</code></td><td><code>'CASCADE'\|'SET NULL'\|'RESTRICT'</code></td><td>删除级联 ✅ v0.4.1</td></tr>
+  <tr><td><code>onUpdate</code></td><td><code>'CASCADE'\|'SET NULL'\|'RESTRICT'</code></td><td>更新级联（更新主键时触发）✅ v0.4.2</td></tr>
 </table>

 <h2 id="sql-query">🔍 SQL 查询</h2>
@@ -549,6 +550,19 @@ db.<span class="f">addMigration</span>(<span class="n">3</span>, <span class="k"

 <span class="c">// 执行迁移到目标版本</span>
 <span class="k">await</span> db.<span class="f">migrateTo</span>(<span class="n">3</span>);  <span class="c">// 依次执行 v2, v3 的迁移函数</span></pre>
+<p>✅ <strong>v0.4.2: 迁移版本持久化到库内</strong> — 重启后从持久化版本继续执行，已执行迁移不重跑（此前 version 每次从 config 重置，可能重跑不幂等的迁移）。</p>
+
+<h2 id="selfheal">🛡 崩溃恢复自愈（v0.4.2）</h2>
+<p>异常退出（强杀/断电）后无需删库重建：打开数据库时自动跳过残缺 SSTable，应用层可调用自愈 API 恢复一致性。</p>
+
+<pre><span class="c">// 自愈 — 校验并清理损坏 SSTable / 重建二级索引 / 截断 WAL</span>
+<span class="k">await</span> db.<span class="f">repair</span>();
+
+<span class="c">// 清空全部数据与表结构（保留库本身，实例可继续使用）</span>
+<span class="k">await</span> db.<span class="f">clearAll</span>();
+
+<span class="c">// 引擎级元数据（迁移版本等）</span>
+<span class="c">// 引擎接口 IStorageEngine 可选扩展：repair() / clearAll() / getMeta() / setMeta()</span></pre>

 <h2 id="export">📤 导入导出</h2>
 <pre><span class="c">// 导出单表 — 返回 JSON 数组</span>
@@ -747,7 +761,8 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
 	<p><strong>v0.2.0 新增</strong> — AriaEngine 是专为 MetonaSqlark 设计的页面式存储引擎，对标 SQLite 设计理念。<br>
 <strong>v0.2.4 生产级</strong> — 二级索引 · MVCC · BloomFilter · WAL CRC全同步 · AES-GCM加密 · Savepoint · EXPLAIN · ANALYZE · REINDEX · VACUUM · BufferPool · 零死代码。<br>
 <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.1 Aria 级联与演示页引擎切换</strong> — AriaEngine 外键级联（CASCADE/SET NULL/RESTRICT）· `clearAll()` 重置 API · 演示页 ⚡Memory/🌲Aria 引擎切换器 · 894测试 47套件。</p>
+<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 等待 · 950 测试 51 套件。</p>

 <h3>存储模式对比</h3>
 <table>
@@ -28,7 +28,7 @@
  "author": "MarkLite",
  "license": "MIT",
  "dependencies": {
-    "@metona-team/metona-editor": "^0.4.0",
+    "@metona-team/metona-editor": "0.4.1",
    "@metona-team/metona-sqlark": "0.4.3",
    "@metona-team/metona-toast": "^0.5.0",
    "mermaid": "^10.9.6",