◈ MetonaSqlark — 前端 TypeScript 数据库

📦 安装引入

多种方式，按需选择

📦

npm (Gitea Registry)

# 配置 registry
npm config set @metona-team:registry https://git.metona.cn/api/packages/MetonaTeam/npm/

# 安装
npm install @metona-team/metona-sqlark
        

🌐

CDN / Browser UMD

<!-- 直接引用 dist 产物 -->
<script src="metona-sqlark.min.js"></script>
<script>
  const db = await window.MetonaSqlark.create({...});
  // 或 window.MeSqlark（别名）
</script>
        

⚡

ESM / TypeScript

import { MetonaSqlark, MeSqlark }
  from '@metona-team/metona-sqlark';

const db = await MetonaSqlark.create({
  name: 'my-app',
  mode: 'hybrid',
});
        

🔧

CommonJS

const { MetonaSqlark } =
  require('@metona-team/metona-sqlark');

(async () => {
  const db = await MetonaSqlark.create({...});
})();
        

为什么选择 MetonaSqlark

专为前端打造的数据库引擎

🧠

5 种存储引擎

Memory / IndexedDB / OPFS / Hybrid / AriaEngine。Aria 是自研 LSM-Tree 页面式引擎，支持 WAL 同步崩溃恢复和 MVCC 事务隔离。

⚡

完整 SQL 解析器

手写递归下降 SQL 解析器。SELECT / INSERT / UPDATE / DELETE / JOIN / GROUP BY / HAVING / DISTINCT / 子查询 / ALTER TABLE / TRUNCATE TABLE。

🌲

AriaEngine v0.6.0

自研 LSM-Tree 存储引擎：SSTable 4KB 页面化物理存储（BufferPool LRU）、WAL 分片文件原子写入、全库 AES-GCM 透明加密、标准 CRC-32 完整性校验、MVCC 快照隔离、二级索引跨重启恢复、ON UPDATE/DELETE 外键级联、崩溃恢复自愈。

🔒

事务回滚 + MVCC

beginTransaction / commitTransaction / rollbackTransaction 三件套。失败自动回滚，Memory 快照 + IndexedDB 延迟写入 + Aria MVCC 版本链。

🔍

子查询 + ALTER TABLE

IN (SELECT ...) + 标量子查询。ALTER TABLE ADD/DROP COLUMN 动态修改表结构，TRUNCATE TABLE 快速清空。

🔗

外键级联 + SQL安全

references + ON DELETE / ON UPDATE CASCADE · SET NULL · RESTRICT（更新主键级联更新子表）。React/Vue hooks 表名合法性校验，防 SQL 注入。

🛡

崩溃恢复自愈

异常退出后无需删库重建：整文件 CRC-32 校验 + 打开自动跳过损坏 SSTable，db.repair() 清理损坏数据/孤儿页面/残留文件并重建索引，db.clearAll() 重置。迁移版本持久化，重启不重跑。

🏊

连接池 + 性能优化

MetonaSqlark.connect() 单例复用。SSTableReader 二分查找统一、IndexedDB 索引利用、crypto 实例化。

🧩

插件系统

14 种生命周期钩子全部真实触发（Table API 与 SQL 双路径）：beforeCreateTable / afterInsert / beforeQuery / afterTransaction……按优先级注册。

📦

零运行时依赖

纯 TypeScript 实现，不依赖任何第三方库。Tree-shakable，UMD/ESM/CJS 多格式输出，~27KB gzip。

📊

聚合 & 分组

COUNT / SUM / AVG / MIN / MAX 五大聚合函数，GROUP BY + HAVING 子句，DISTINCT 去重。

🔐

全库加密 + 多标签页锁

encryption.password 一键启用 AES-256-GCM 全库透明加密（密码验证 + 篡改检测）。Web Locks 独占锁：第二个标签页打开同一库抛 ARIA_LOCKED。

🛠

维护语句（SQL）

EXPLAIN 查询计划 · ANALYZE 表统计 · REINDEX 重建索引 · VACUUM 压缩 · SAVEPOINT 嵌套事务保存点 — 全部原生 SQL 语法。

🔄

数据迁移

内置版本迁移系统，addMigration + migrateTo API。导入导出支持单表/全库 JSON 序列化，db.backup() 在线一致性备份。

📡

发布订阅 + 框架集成

subscribe() 订阅表变更。React useQuery / Vue useSqlarkQuery 开箱即用。

🔗

Query Builder

链式 API + TypeScript 泛型。.select().where().innerJoin().orderBy().limit() — 类型安全，IDE 友好。

🚰

流式查询 + 派生表

queryStream 逐行回调不物化结果集（大表友好）。FROM (SELECT ...) 派生表、多列哈希连接、COUNT(DISTINCT)、NULLS FIRST/LAST。

🏗 架构设计

清晰的分层结构，各模块职责单一

	  ┌──────────────────────────────────────────────────────────┐
	  │                    MetonaSqlark / MeSqlark                     │
	  │              create() · query() · table() · tx()          │
	  ├──────────┬──────────┬──────────┬──────────┬──────────────┤
	  │ SQL Parser │ QueryBuilder │ Transaction│ Plugin   │ Migration    │
	  │ Lexer →   │ .select() │ Manager  │ Manager  │ System       │
	  │ Parser    │ .where()  │          │ 14 hooks │              │
	  ├──────────┴──────────┴──────────┴──────────┴──────────────┤
	  │              QueryExecutor (AST → Results)                    │
	  │         JOIN · GROUP BY · HAVING · DISTINCT · Subquery     │
	  ├──────────────────────────────────────────────────────────┤
	  │              IStorageEngine Interface                        │
	  ├──────────┬──────────┬──────────┬──────────┬──────────────┤
	  │ Memory    │ IndexedDB │ OPFS     │ Hybrid    │ AriaEngine 🆕 │
	  │ Engine   │ Engine   │ Engine   │ Engine   │ LSM-Tree     │
	  │ (Map)    │ (IDB)    │ (File)   │ (W-Thru) │ WAL + MVCC   │
	  └──────────┴──────────┴──────────┴──────────┴──────────────┘

5 行代码开始

SQL + Query Builder 双 API — JOIN · 子查询 · 聚合 · 事务回滚 · 外键级联 · 连接池 · AriaEngine · ALTER TABLE · TRUNCATE

// 创建数据库 — MeSqlark 是别名，完全等价
const db = await MetonaSqlark.create({ name: 'my-app', mode: 'hybrid' });

// 定义表结构 — 支持外键级联
await db.defineTable('users', {
  id: { type: 'string', primaryKey: true },
  name: { type: 'string', required: true },
  age: { type: 'number', default: 0 },
  email: { type: 'string', unique: true, index: true },
});

// SQL 查询
await db.query("INSERT INTO users VALUES ('1', 'Alice', 30, 'alice@demo.com')");
const rows = await db.query('SELECT * FROM users WHERE age > 18 ORDER BY name');

// Query Builder — 类型安全，链式调用
const rows2 = await db.table('users')
  .select(['name', 'age']).where({ age: { $gt: 18 } })
  .orderBy('name').limit(10).execute();

// JOIN 多表关联
await db.query(`SELECT u.name, o.product, o.amount
  FROM users u INNER JOIN orders o ON u.id = o.user_id
  WHERE o.amount > 100`);

// GROUP BY 聚合分析
await db.query(`SELECT dept, COUNT(*) as cnt, AVG(salary) as avg
  FROM employees GROUP BY dept HAVING COUNT(*) > 1`);

// 事务 — 失败自动回滚
await db.transaction(async (trx) => {
  await trx.table('users').insert({ id: '3', name: 'Charlie' });
  await trx.table('orders').insert({ id: 'o1', userId: '3', amount: 99 });
  // 任何一步失败 → 自动回滚
});

// 子查询 — IN (SELECT ...)
await db.query(`SELECT * FROM users
  WHERE id IN (SELECT user_id FROM orders WHERE amount > 100)`);

// 连接池 — 单例复用，避免重复打开 IndexedDB
const db1 = await MetonaSqlark.connect({ name: 'my-app' });
const db2 = await MetonaSqlark.connect({ name: 'my-app' });
// db1 === db2（复用已有实例）
await db2.disconnect(); // 引用计数 -1，归零时自动 close

前端的 SQL 数据库