📦 安装

MetonaSqlark 支持多种引入方式，覆盖 npm、CDN、ESM、CJS 所有常见场景。

npm 安装（推荐）

# 配置 Gitea Registry（一次性）
npm config set @metona-team:registry https://git.metona.cn/api/packages/MetonaTeam/npm/

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

CDN / UMD

<!-- UMD 格式，暴露 window.MetonaSqlark 和 window.MeSqlark -->
<script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script>
<script>
  const db = await window.MetonaSqlark.create({...});
  // 或 window.MeSqlark.create(...)  — 完全等价
</script>

ESM

import { MetonaSqlark, MeSqlark } from '@metona-team/metona-sqlark';
// MeSqlark 是 MetonaSqlark 的别名，行为完全一致

CJS

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

输出文件说明：

🏗 创建数据库

MetonaSqlark.create(config) — 工厂函数，自动创建并初始化数据库实例。

const db = await MetonaSqlark.create({
  name: 'my-app',
  mode: 'hybrid',       // 'memory' | 'disk' | 'hybrid' | 'aria' 🆕
  diskEngine: 'indexeddb', // 'indexeddb' | 'opfs'（仅 disk/hybrid 生效）
  version: 1,
  plugins: [],            // MetonaPlugin[]
  onReady: (db) => {},    // 就绪回调
  onError: (err) => {},   // 错误回调
});

// 也可手动实例化
const db2 = new MetonaSqlark(config);
await db2.init();

// 检查状态
db.isReady();  // true

// 关闭
await db.close();

📋 定义表

使用 db.defineTable(name, columns) 定义表结构。

await db.defineTable('users', {
  id:       { type: 'string',  primaryKey: true },
  name:     { type: 'string',  required: true },
  email:    { type: 'string',  unique: true, index: true },
  age:      { type: 'number',  default: 0, min: 0, max: 150 },
  active:   { type: 'boolean', default: true },
  birthday: { type: 'date' },
  meta:     { type: 'json' },
  dept_id:  { type: 'number',  references: 'departments.id' },
});

// 表操作
await db.getTableNames();         // ['users']
await db.dropTable('users');     // 删除表

🔍 SQL 查询

db.query(sql) — 执行标准 SQL 字符串，返回查询结果。

db.queryStream(sql, onRow) — 流式查询（v0.4.0）：逐行回调不物化结果集，大表友好。支持简单 SELECT（WHERE/LIMIT/OFFSET/列投影）；JOIN/GROUP BY/UNION/聚合/ORDER BY 自动回退物化。

// 流式查询 — 大表逐行处理
let count = 0;
await db.queryStream("SELECT * FROM logs WHERE level = 'error'", (row) => {
  count++;
  processRow(row);
});

// 派生表 / COUNT(DISTINCT) / NULLS 排序（v0.4.0）
const top = await db.query(`SELECT dept, total FROM
  (SELECT dept, SUM(salary) AS total FROM emp GROUP BY dept) AS t
  WHERE total > 100 ORDER BY total DESC`);
await db.query("SELECT COUNT(DISTINCT city) AS n FROM users");
await db.query("SELECT name FROM users ORDER BY age ASC NULLS FIRST");

完整 SQL 语法支持

// SELECT — 核心查询
const rows = await db.query(`SELECT * FROM users
  WHERE age > 18
  ORDER BY name ASC
  LIMIT 10 OFFSET 0`);

// INSERT — 插入数据
await db.query("INSERT INTO users (id, name, age) VALUES ('1', 'Alice', 30)");
await db.query("INSERT INTO users VALUES ('2', 'Bob', 25)");
// 支持多行插入
await db.query("INSERT INTO users VALUES ('3', 'C'), ('4', 'D')");

// UPDATE — 更新数据
await db.query("UPDATE users SET age = 31, active = true WHERE id = '1'");

// DELETE — 删除数据
await db.query("DELETE FROM users WHERE id = '1'");

// DDL — 表结构操作
await db.query(`CREATE TABLE products (
  id STRING PRIMARY KEY,
  name STRING NOT NULL,
  price NUMBER DEFAULT 0
)`);
await db.query('DROP TABLE products');

-- ALTER TABLE — 动态修改表结构 (v0.2.5)
await db.query('ALTER TABLE users ADD COLUMN phone STRING');
await db.query('ALTER TABLE users DROP COLUMN phone');

-- TRUNCATE TABLE — 快速清空表数据 (v0.2.5)
await db.query('TRUNCATE TABLE old_logs');

SQL 扩展 (v0.3.0+)

// 多语句 — 分号分隔一次执行（返回最后一条结果）
await db.query(`CREATE TABLE t (id STRING PRIMARY KEY);
  INSERT INTO t VALUES ('1'); INSERT INTO t VALUES ('2')`);

// 事务语句 — BEGIN / COMMIT / ROLLBACK
await db.query('BEGIN');
await db.query("INSERT INTO t VALUES ('3')");
await db.query('ROLLBACK'); // 回滚

// INSERT INTO ... SELECT — 查询结果写入
await db.query('INSERT INTO t SELECT id FROM t2 WHERE x > 1');

// UNION / UNION ALL — 合并查询
const merged = await db.query(
  `SELECT name FROM users WHERE city = 'Beijing'
   UNION SELECT name FROM users WHERE age < 30`);

// EXISTS / NOT EXISTS — 关联子查询
const hasOrders = await db.query(`SELECT * FROM users u
  WHERE EXISTS (SELECT 1 FROM orders o WHERE o.user_id = u.id)`);

// CASE WHEN — SELECT 列 / WHERE / 聚合 (v0.3.1 / v0.3.2)
const labeled = await db.query(`SELECT name,
  CASE WHEN age >= 18 THEN 'adult' ELSE 'minor' END AS status FROM users`);
const adults = await db.query(`SELECT SUM(CASE WHEN age >= 18 THEN 1 ELSE 0 END) FROM users`);

// CREATE / DROP INDEX — 动态二级索引
await db.query('CREATE INDEX idx_users_city ON users (city)');
await db.query('DROP INDEX idx_users_city ON users (city)');

条件表达式

// 比较运算符
`WHERE age > 18 AND name LIKE 'A%'`
`WHERE salary >= 5000 OR dept = 'Engineering'`

// IN / NOT IN
`WHERE dept IN ('Engineering', 'Sales')`

// NULL 检查
`WHERE email IS NULL`
`WHERE email IS NOT NULL`

// NOT 取反
`WHERE NOT (age < 18 OR age > 65)`

// 嵌套条件
`WHERE (age > 18 AND active = true) OR role = 'admin'`

⛓ Query Builder

链式 API，TypeScript 友好，享受 IDE 自动补全。

SELECT

const users = db.table('users');

// 全量查询
await users.select().execute();

// 指定列 + 条件 + 排序 + 分页
const result = await users
  .select(['name', 'age', 'email'])
  .where({
    age: { $gt: 18 },
    name: { $like: 'A%' },
  })
  .orderBy('age', 'desc')
  .limit(10)
  .offset(0)
  .execute();

INSERT

// 单行插入 — 返回主键值
const pk = await users.insert({ id: '1', name: 'Alice', age: 30 });

// 批量插入 — 返回主键值数组
const pks = await users.insertMany([
  { id: '2', name: 'Bob', age: 25 },
  { id: '3', name: 'Charlie', age: 35 },
]);

UPDATE / DELETE

// 更新 — 返回影响行数
const updated = await users
  .update({ age: 31, active: false })
  .where({ id: '1' })
  .execute();  // 1

// 删除 — 返回影响行数
const deleted = await users
  .delete()
  .where({ id: '1' })
  .execute();  // 1

// 全表删除
await users.delete().execute();

🔗 JOIN 查询

支持 INNER / LEFT / RIGHT / CROSS JOIN，SQL 和 Query Builder 两种方式。

// SQL 方式 — 支持表别名
await db.query(`SELECT u.name, d.name AS dept_name
  FROM users u
  INNER JOIN departments d ON u.dept_id = d.id
  LEFT JOIN orders o ON u.id = o.user_id
  WHERE d.name = 'Engineering'
  ORDER BY u.name`);

// Query Builder 方式
await db.table('users').select()
  .as('u')
  .innerJoin('departments', { 'u.dept_id': { $col: 'd.id' } }, 'd')
  .leftJoin('orders', { 'u.id': { $col: 'o.user_id' } }, 'o')
  .execute();

// CROSS JOIN — 笛卡尔积
.crossJoin('metadata', 'm')

📊 GROUP BY & 聚合

五大聚合函数 + GROUP BY + HAVING + DISTINCT，完整的数据分析能力。

// GROUP BY + 聚合
await db.query(`SELECT dept, COUNT(*) as cnt, SUM(salary) as total,
       AVG(salary) as avg_sal, MIN(age), MAX(age)
  FROM employees
  GROUP BY dept
  HAVING COUNT(*) > 1
  ORDER BY total DESC
  LIMIT 5`);

// DISTINCT 去重
await db.query('SELECT DISTINCT dept FROM employees');

// 聚合函数别名
await db.query('SELECT COUNT(*) AS total_users, AVG(age) AS avg_age FROM users');

🎯 WHERE 操作符

Query Builder 使用 $ 前缀操作符，支持逻辑组合。

// 复合条件
.where({
  $or: [
    { age: { $lt: 18 } },
    { age: { $gt: 65 } },
  ],
  active: true,
  name: { $like: 'A%', $ne: 'Admin' },
})

🔒 事务 & 回滚

v0.1.13 起支持真正的自动回滚：事务内任何一步失败，所有变更自动撤销。

await db.transaction(async (trx) => {
  // trx.table() 获取事务内表操作对象
  await trx.table('users').insert({ id: '3', name: 'Charlie' });
  await trx.table('orders').insert({ id: 'o1', userId: '3', amount: 99 });
  // ✅ 全部成功 → 自动 commit
  // ❌ 任何一步失败 → 自动 rollback，数据恢复原状
  // Memory 引擎：快照回滚 | IndexedDB 引擎：延迟写入
});

🔍 子查询

v0.1.13 新增子查询支持，可在 WHERE 条件中嵌套 SELECT。

// IN 子查询 — 查询有高额订单的用户
await db.query(`SELECT * FROM users
  WHERE id IN (SELECT user_id FROM orders WHERE amount > 100)`);

// 标量子查询 — 查询年龄等于平均年龄的用户
await db.query(`SELECT * FROM users
  WHERE age = (SELECT AVG(age) FROM users)`);

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

🏗 ALTER TABLE (🆕 v0.2.5)

v0.2.5 新增 ALTER TABLE 语法，支持动态添加和删除列。

ADD COLUMN

-- 添加新列
await db.query('ALTER TABLE users ADD COLUMN phone STRING');

-- 带约束的添加
await db.query('ALTER TABLE users ADD COLUMN email STRING UNIQUE');

-- 带可选 COLUMN 关键字
await db.query('ALTER TABLE users ADD COLUMN age NUMBER DEFAULT 0');

DROP COLUMN

-- 删除列
await db.query('ALTER TABLE users DROP COLUMN phone');

-- 带可选 COLUMN 关键字
await db.query('ALTER TABLE users DROP COLUMN email');

🗑 TRUNCATE TABLE (🆕 v0.2.5)

v0.2.5 新增 TRUNCATE TABLE 语法，快速清空表数据（保留表结构）。

-- 快速清空表数据
await db.query('TRUNCATE TABLE old_logs');

-- 等价于 DELETE FROM old_logs，但语义更清晰

🔗 外键级联

v0.1.13 支持外键级联操作，定义表时可指定 ON DELETE / ON UPDATE 行为。

// 定义时指定外键 + 级联策略
await db.defineTable('orders', {
  id: { type: 'string', primaryKey: true },
  user_id: {
    type: 'string',
    references: 'users.id',
    onDelete: 'CASCADE',  // 删除用户时级联删除订单
    onUpdate: 'RESTRICT', // 禁止更新被引用的用户 ID
  },
  amount: { type: 'number' },
});

// SQL DDL 同样支持
await db.query(`CREATE TABLE orders (
  id STRING PRIMARY KEY,
  user_id STRING REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT,
  amount NUMBER
)`);

// 删除用户 → 其所有订单自动删除
await db.query("DELETE FROM users WHERE id = '1'");

🏊 连接池

v0.1.13 新增连接池管理器，避免重复创建同名数据库实例。

// connect() — 获取或创建实例（单例复用）
const db1 = await MetonaSqlark.connect({ name: 'my-app', mode: 'hybrid' });
const db2 = await MetonaSqlark.connect({ name: 'my-app' });
// db1 === db2 — 复用已有实例，避免重复 open IndexedDB

// disconnect() — 释放连接（引用计数 -1）
await db2.disconnect(); // 引用计数: 2 → 1
await db1.disconnect(); // 引用计数: 1 → 0，自动 close()

// disconnectAll() — 强制关闭所有连接
await MetonaSqlark.disconnectAll();

// getActiveConnections() — 查看活跃连接
MetonaSqlark.getActiveConnections(); // ['my-app']

🔄 数据迁移

按版本号管理表结构变更。

// 注册迁移
db.addMigration(2, async (db) => {
  await db.defineTable('products', {
    id: { type: 'string', primaryKey: true },
    name: { type: 'string', required: true },
  });
});

db.addMigration(3, async (db) => {
  // 添加新列、数据迁移等
  await db.query("UPDATE users SET role = 'user' WHERE role IS NULL");
});

// 执行迁移到目标版本
await db.migrateTo(3);  // 依次执行 v2, v3 的迁移函数

📤 导入导出

// 导出单表 — 返回 JSON 数组
const userData = await db.exportTable('users');
// [{ id: '1', name: 'Alice', ... }, ...]

// 导出全库 — 返回 { tableName: rows[] }
const allData = await db.exportAll();
// { users: [...], orders: [...], products: [...] }

// 导入数据 — 返回主键列表
const pks = await db.importTable('users', userData);

🧩 插件 & 钩子

14 种生命周期钩子，支持插件机制。

// 注册钩子
db.on('beforeInsert', async (row) => {
  console.log('即将插入:', row);
  // 可在此校验、转换数据
});

db.on('afterQuery', async (sql, result) => {
  console.log(`查询完成 [${sql}] → ${(result as any[]).length} 行`);
});

// 注册自定义插件
const loggerPlugin = {
  name: 'logger',
  version: '1.0.0',
  description: '记录所有数据库操作',
  priority: 100,
  install(db) {
    db.on('beforeQuery', (sql) => console.log('SQL:', sql));
  },
  destroy() { /* 清理 */ },
};

// 在 create 配置中注册
const db = await MetonaSqlark.create({
  name: 'my-app',
  plugins: [loggerPlugin],
});

📡 发布订阅

// 订阅表变更
const unsubscribe = db.subscribe('users', (event) => {
  // event.type: 'insert' | 'update' | 'delete'
  // event.row:  被操作的行数据
  console.log(`users 表 ${event.type}`, event.row);
});

// 手动触发变更
db.emit('users', { type: 'insert', row: { id: '1', name: 'Alice' } });

// 取消订阅
unsubscribe();

多标签页同步 (v0.3.2)

// 启用 multiTabSync 后，其他标签页的写操作会广播到此标签页
const db = await MetonaSqlark.create({
  name: 'my-app',
  mode: 'hybrid',
  multiTabSync: true,
});

// 订阅其他标签页的变更（event.type === 'external'）
db.subscribe('users', (event) => {
  if (event.type === 'external') {
    // Hybrid 模式已自动从磁盘重载，此处可刷新 UI
    refreshList();
  }
});

// 手动广播（Table API 已自动广播；自定义写入可调用）
db.broadcastChange('users');

⚛️ React 集成

import { useQuery, useTable, useDatabase } from '@metona-team/metona-sqlark/react';
import { db } from './db';

function UserList() {
  // 执行 SQL 查询，自动响应 db 变化
  const { data, loading, error, refresh } = useQuery(
    db,
    'SELECT * FROM users WHERE age > 18',
    [/* deps */]
  );

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      {data.map(u => <div key={u.id}>{u.name} ({u.age})</div>)}
      <button onClick={refresh}>刷新</button>
    </div>
  );
}

// 便捷 hook — 查询整张表
const { data, loading, refresh } = useTable(db, 'users');

// 管理数据库生命周期
function App() {
  const { db, ready, error } = useDatabase({
    name: 'my-app',
    mode: 'hybrid',
  });
  if (!ready) return <div>Initializing...</div>;
  return <UserList />;
}

🟢 Vue 集成

import { useSqlarkQuery, useSqlarkTable, useSqlarkDatabase }
  from '@metona-team/metona-sqlark/vue';
import { db } from './db';

// useSqlarkQuery — 执行 SQL 查询
const { data, loading, error, refresh } = useSqlarkQuery(
  db,
  'SELECT * FROM users WHERE age > 18'
);

// useSqlarkTable — 获取全表数据
const { data, loading, refresh } = useSqlarkTable(db, 'users');

// useSqlarkDatabase — 管理数据库生命周期
const { db, ready, error } = useSqlarkDatabase({
  name: 'my-app',
  mode: 'hybrid',
});

🔷 TypeScript 泛型

interface User {
  id: string;
  name: string;
  age: number;
  email?: string;
}

// 泛型表操作 — 类型安全的 insert/select
const users = db.table<User>('users');

// ✅ 类型检查通过
await users.insert({ id: '1', name: 'Alice', age: 30 });

// ❌ TypeScript 报错：缺少 name
// await users.insert({ id: '2', age: 25 });

⚙️ 完整配置项

💾 存储引擎

🌲 AriaEngine 自研存储引擎

v0.2.0 新增 — AriaEngine 是专为 MetonaSqlark 设计的页面式存储引擎，对标 SQLite 设计理念。
v0.2.4 生产级 — 二级索引 · MVCC · BloomFilter · WAL CRC全同步 · AES-GCM加密 · Savepoint · EXPLAIN · ANALYZE · REINDEX · VACUUM · BufferPool · 零死代码。
v0.3.2 表达式与并发 — WAL full模式真正同步 · MVCC接入读写路径 · SSTableReader二分查找统一 · crypto实例化 · IndexedDB索引利用 · compactLevel public接口 · WAL大小阈值自动checkpoint · SQL注入防护 · ALTER TABLE · TRUNCATE TABLE · 多标签页同步 · IDB schema持久化。
v0.4.1 Aria 级联与演示页引擎切换 — AriaEngine 外键级联（CASCADE/SET NULL/RESTRICT）· `clearAll()` 重置 API · 演示页 ⚡Memory/🌲Aria 引擎切换器 · 894测试 47套件。

存储模式对比

核心特性

使用方式

// 激活 AriaEngine
	const db = await MetonaSqlark.create({
	  name: 'my-app',
	  mode: 'aria',             // 🆕 AriaEngine 模式
	  diskEngine: 'indexeddb',   // 底层存储后端（indexeddb | opfs | memory）
	});

	// 或直接实例化 — 支持细粒度配置
	import { AriaEngine } from '@metona-team/metona-sqlark';
	const engine = new AriaEngine({
	  pageSize: 4096,               // 页面大小
	  bufferPoolPages: 256,       // 缓存页数
	  memtableSizeThreshold: 4194304, // MemTable 刷盘阈值 4MB
	  walEnabled: true,            // 启用 WAL
	  walSyncMode: 'batch',        // 'full' | 'batch' | 'none'
	  storageBackend: 'indexeddb', // 存储后端
	});

AriaEngine 配置项

⚠️ 错误处理

所有错误抛出 DatabaseError 实例。

try {
  await db.query('SELECT * FROM nonexistent');
} catch (err) {
  if (err instanceof DatabaseError) {
    console.log(err.message);  // 'Table "nonexistent" does not exist'
    console.log(err.code);    // 'TABLE_NOT_FOUND'
    console.log(err.details); // 附加信息
  }
}