release: v0.4.2 — 生产就绪与崩溃自愈 + 问题清单修复 + 版本迭代

2026-08-09 19:15:37 +08:00
parent a1e4f5071c
commit 22b0b1fad4
34 changed files with 6626 additions and 565 deletions
@@ -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.2</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,7 @@ 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()` 统一自愈接口 · 迁移版本持久化到库内 · 944 测试 50 套件。</p>

 <h3>存储模式对比</h3>
 <table>