docs: site 站点全量同步 v0.7.3 — 首页徽章/统计数字（1256测试 75套件 90.0%）、API 文档补参数化查询与维护语句章节 + v0.6.2~v0.7.3 里程碑记录、错误码表补 PARAM_ERROR/QUERY_ERROR、演示/基准版本标注
This commit is contained in:
thzxx
+38
-5
@@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>📖 API 文档 — MetonaSqlark v0.6.1</title>
|
||||
<title>📖 API 文档 — MetonaSqlark v0.7.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 {
|
||||
@@ -152,7 +152,7 @@ npm install @metona-team/metona-sqlark</pre>
|
||||
<pre><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">'hybrid'</span>, <span class="c">// 'memory' | 'disk' | 'hybrid' | 'aria' 🆕</span>
|
||||
<span class="s">diskEngine</span>: <span class="s">'opfs'</span>, <span class="c">// 'opfs' | 'memory'（v0.6.0: IndexedDB 已移除）</span>
|
||||
<span class="s">diskEngine</span>: <span class="s">'opfs'</span>, <span class="c">// 'opfs' | 'kv' | 'memory'（v0.6.0: IndexedDB 已移除）</span>
|
||||
<span class="s">version</span>: <span class="n">1</span>,
|
||||
<span class="s">plugins</span>: [], <span class="c">// MetonaPlugin[]</span>
|
||||
<span class="s">onReady</span>: (db) => {}, <span class="c">// 就绪回调</span>
|
||||
@@ -254,6 +254,14 @@ db.<span class="f">isReady</span>(); <span class="c">// true</span>
|
||||
<span class="c">-- TRUNCATE TABLE — 快速清空表数据 (v0.2.5)</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'TRUNCATE TABLE old_logs'</span>);</pre>
|
||||
|
||||
<h3>参数化查询 (v0.7.0)</h3>
|
||||
<p>位置参数 <code>?</code> 在词法层安全绑定（仅替换字符串字面量与注释之外的占位符），值按 SQL 字面量编码 —— 杜绝 SQL 注入，无需手动转义。</p>
|
||||
<pre><span class="c">// 位置参数绑定 — 字符串 '' 转义自动完成</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">"INSERT INTO users VALUES (?, ?, ?, ?)"</span>, [<span class="s">'2'</span>, <span class="s">"O'Brien"</span>, <span class="n">25</span>, <span class="s">'ob@demo.com'</span>]);
|
||||
<span class="k">const</span> row = <span class="k">await</span> db.<span class="f">query</span>(<span class="s">'SELECT * FROM users WHERE name = ?'</span>, [<span class="s">"O'Brien"</span>]);
|
||||
|
||||
<span class="c">// 参数数量不匹配 → PARAM_ERROR；对象/数组参数显式拒绝；NaN/Infinity → NULL</span></pre>
|
||||
|
||||
<h3>SQL 扩展 (v0.3.0+)</h3>
|
||||
<pre><span class="c">// 多语句 — 分号分隔一次执行（返回最后一条结果）</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">`CREATE TABLE t (id STRING PRIMARY KEY);
|
||||
@@ -285,6 +293,23 @@ db.<span class="f">isReady</span>(); <span class="c">// true</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'CREATE INDEX idx_users_city ON users (city)'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'DROP INDEX idx_users_city ON users (city)'</span>);</pre>
|
||||
|
||||
<h3>维护语句 (v0.5.1 SQL 入口)</h3>
|
||||
<pre><span class="c">// EXPLAIN — 查询计划（真实索引命中信息 v0.7.0）</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">"EXPLAIN SELECT * FROM users WHERE email = 'a@x.com'"</span>);
|
||||
<span class="c">// { type, table, usingIndex: 'index:email', estimatedRows, actualTimeMs, ... }</span>
|
||||
|
||||
<span class="c">// ANALYZE / REINDEX / VACUUM（Aria 引擎；v0.7.3 统计含二级索引）</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'ANALYZE users'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'REINDEX users'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'VACUUM'</span>);
|
||||
|
||||
<span class="c">// SAVEPOINT — 嵌套事务保存点</span>
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'BEGIN'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'SAVEPOINT sp1'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'ROLLBACK TO SAVEPOINT sp1'</span>);
|
||||
<span class="k">await</span> db.<span class="f">query</span>(<span class="s">'RELEASE SAVEPOINT sp1'</span>);
|
||||
<span class="c">// 不支持的引擎执行维护语句抛 NOT_SUPPORTED</span></pre>
|
||||
|
||||
<h3>条件表达式</h3>
|
||||
<pre><span class="c">// 比较运算符</span>
|
||||
<span class="s">`WHERE age > 18 AND name LIKE 'A%'`</span>
|
||||
@@ -737,7 +762,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<tr><th>属性</th><th>类型</th><th>默认值</th><th>说明</th></tr>
|
||||
<tr><td><code>name</code></td><td><code>string</code></td><td><code>'metona-sqlark'</code></td><td>数据库名称（必填）</td></tr>
|
||||
<tr><td><code>mode</code></td><td><code>'memory'|'disk'|'hybrid'|'aria'</code></td><td><code>'hybrid'</code></td><td>存储模式 🆕 aria</td></tr>
|
||||
<tr><td><code>diskEngine</code></td><td><code>'opfs'|'memory'</code></td><td><code>'opfs'</code></td><td>磁盘引擎类型（v0.6.0: IndexedDB 已移除）</td></tr>
|
||||
<tr><td><code>diskEngine</code></td><td><code>'opfs'|'memory'|'kv'</code></td><td><code>'opfs'</code></td><td>磁盘引擎类型（'kv' = 自研 KVStore 后端；v0.6.0: IndexedDB 已移除）</td></tr>
|
||||
<tr><td><code>version</code></td><td><code>number</code></td><td><code>1</code></td><td>数据库版本号</td></tr>
|
||||
<tr><td><code>plugins</code></td><td><code>MetonaPlugin[]</code></td><td><code>[]</code></td><td>初始插件列表</td></tr>
|
||||
<tr><td><code>onReady</code></td><td><code>(db) => void</code></td><td>-</td><td>初始化完成回调</td></tr>
|
||||
@@ -768,7 +793,13 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<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+ 统计辅助方法）。<br>
|
||||
<strong>v0.6.0 完全移除 IndexedDB</strong> — 自研 KVStore 事务存储引擎（多 key 原子写 = 单日志记录原子追加 · 快照 checkpoint + 两阶段崩溃恢复 · CRC-32 自愈）· disk 模式切换 KVStoreEngine（替代 IndexedDBEngine + OPFSEngine）· 事务内 DDL / 外键级联 / 二级索引完整持久化 · migrateFromIndexedDB() 旧库一键迁移 · 10 万 key 压力验证 · e2e 崩溃注入 + KVStoreEngine 真实环境（12 用例）。<br>
|
||||
<strong>v0.6.1 生产可用性深度审查</strong> — MemoryEngine 级联环（A→B→A）无限递归修复（visited 保护，与 Aria 对齐）· KVStore 快照损坏水位 bug 修复（metaSeq 误跳日志）· 多表事务 / 级联写入合并单条日志记录真原子（崩溃无部分提交）· 未 open 防护统一 · <strong>AriaEngine 可选自研 KVStore 后端</strong>（storageBackend: 'kv'：KVStore APPEND 日志支持 WAL 追加、writeMany 真原子、不再依赖浏览器 OPFS）· 二级索引范围扫描尾块漏读 P0 修复 · 批量插入性能悬崖修复（10 万行 kv 后端 353s → 12.5s）· 页面 id 崩溃回退 / flush 并发写 meta 两个崩溃恢复 P0 修复 · 10 万级 kv/opfs 双后端回归 · 1093 测试 70 套件 · 89.7% 行覆盖率。</p>
|
||||
<strong>v0.6.1 生产可用性深度审查</strong> — MemoryEngine 级联环（A→B→A）无限递归修复（visited 保护，与 Aria 对齐）· KVStore 快照损坏水位 bug 修复（metaSeq 误跳日志）· 多表事务 / 级联写入合并单条日志记录真原子（崩溃无部分提交）· 未 open 防护统一 · <strong>AriaEngine 可选自研 KVStore 后端</strong>（storageBackend: 'kv'：KVStore APPEND 日志支持 WAL 追加、writeMany 真原子、不再依赖浏览器 OPFS）· 二级索引范围扫描尾块漏读 P0 修复 · 批量插入性能悬崖修复（10 万行 kv 后端 353s → 12.5s）· 页面 id 崩溃回退 / flush 并发写 meta 两个崩溃恢复 P0 修复 · 10 万级 kv/opfs 双后端回归。<br>
|
||||
<strong>v0.6.2 深度审计修复（数据正确性专项）</strong> — KVStoreEngine 数值主键 update 丢行 P0 · update 主键变更撞已有主键静默覆盖 P0 · Aria 二级索引范围查询边界算法错误（小数/字符串静默丢数据）P1 · 索引列 IS NULL 恒空（Aria）P1 · Aria unique 约束未强制（批内互查 + 索引前缀扫描）· 非主键 update 索引旧值残留 · EXPLAIN 写语句产生真实副作用修复。<br>
|
||||
<strong>v0.6.3 原子性 / 一致性 / 资源治理</strong> — KVStore 混合写单记录真原子（writeBatch，主键变更/级联全有或全无）· WAL full 模式写入失败抛错（不再吞错）· Memory SET NULL 级联索引残留 · delete 级联两阶段 RESTRICT 预检（无事务部分级联修复）· BufferPool 驱逐清理 pages Map（内存预算真实生效）· MVCC 已提交版本清理 · LSM.flush 重复入链 · rollbackToSavepoint 重建二级索引。<br>
|
||||
<strong>v0.7.0 参数化查询 / 事务性能 / 语义硬化</strong> — <strong>参数化查询</strong>（<code>db.query(sql, params)</code> 位置参数 `?`，词法层绑定 + SQL 字面量安全编码，注入防护从根上成立）· EXPLAIN 真实索引命中信息（pk / index:col）· KVStoreEngine 事务行级增量 flush（大表事务改 1 行 commit 仅 1 条记录）· 移除每次 commit 强制全量 checkpoint · 复合主键显式拒绝（SCHEMA_ERROR，v0.8 路线图）。<br>
|
||||
<strong>v0.7.1 API 修复与防御统一</strong> — <code>MetonaSqlark.create</code> 静态工厂（README 示例在 ESM/Node 下可用）· close 未初始化崩溃防御 · AriaEngine 未 open 防护统一 · 事务回滚失败不掩盖原始错误 · <code>__proto__</code> 列名原型污染防护 · lint 清零。<br>
|
||||
<strong>v0.7.2 语句级原子性 / 事务 DDL / 约束硬化</strong> — UPDATE 语句级两阶段原子（多行匹配第 N 行失败整句不执行 + 批内唯一互查）· 事务内 DDL 显式拒绝（四引擎对齐）· SET NULL 级联绕过 required 约束整体拒绝 · 参数绑定注释感知（注释中 `?`/引号不参与绑定）· 未闭合字符串显式 PARSE_ERROR · 未知 where 操作符抛 QUERY_ERROR（此前静默全匹配）· update undefined 语义化（保留旧值）· Hybrid write-through 失败补偿（磁盘失败自动重载内存对齐）。<br>
|
||||
<strong>v0.7.3 深度审计第六阶段：INSERT 原子 / 索引一致性 / 边界窗口</strong> — INSERT 语句级两阶段原子（三引擎 + Aria PK 批内重复，此前部分提交）· 索引列 IS NULL 恒空修复（Memory/KVStore/Hybrid，对齐 Aria）· delete RESTRICT 预检不再破坏索引 · queryStream 子查询静默空结果修复（$subquery/$exists/$col 回退物化）· ALTER DROP 索引列残留清理 · CREATE UNIQUE INDEX 存量重复数据校验（失败原子回滚）· <code>SELECT *, col AS alias</code> 解析与投影 · WAL BEGIN/ROLLBACK 写失败窗口修复（事务不泄漏/数据不复活）· aria $in 批级预加载（消除逐值 drainChain 性能悬崖）· 多条件 AND 等值下推（索引真正生效，EXPLAIN 同步）· ANALYZE 统计含二级索引 · React/Vue hooks 生命周期修复（config 变更重建 / 卸载关闭）· 迁移无主键旧库兜底 · 1256 测试 75 套件 · 90.0% 行覆盖率。</p>
|
||||
|
||||
<h3>存储模式对比</h3>
|
||||
<table>
|
||||
@@ -833,7 +864,7 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<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>'opfs'|'memory'|'kv'</code></td><td><code>'opfs'</code></td><td>存储后端类型（'kv' = 自研 KVStore 后端 🆕 v0.6.1）</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>
|
||||
<tr><td><code>pageStorage</code></td><td><code>boolean</code></td><td>opfs/kv 自动启用</td><td>SSTable 4KB 页面化物理存储（BufferPool 缓存）🆕 v0.5.0</td></tr>
|
||||
</table>
|
||||
|
||||
<h2 id="errors">⚠️ 错误处理</h2>
|
||||
@@ -870,6 +901,8 @@ db.<span class="f">broadcastChange</span>(<span class="s">'users'</span>);</pre>
|
||||
<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>
|
||||
<tr><td><code>PARAM_ERROR</code></td><td>参数绑定错误：数量不匹配 / 对象数组参数 🆕 v0.7.0</td></tr>
|
||||
<tr><td><code>QUERY_ERROR</code></td><td>未知 where 操作符（如拼错的 <code>$betwen</code>）🆕 v0.7.2</td></tr>
|
||||
</table>
|
||||
|
||||
</main>
|
||||
|
||||
Reference in New Issue
Block a user