JSQL-neo
Rust 驱动的嵌入式数据库,一个 npm 包说三种协议。
✨ 一句话概括
JSQL-neo 是一个用 Rust 写核心、用 JavaScript 做 API 层的嵌入式数据库引擎。它把三件事塞进了一个 npm 包:
- 三种引擎 —— Native(Rust N-API)、WASM(浏览器/Node 通用)、Pure JS(零原生依赖)
- 三种协议 —— MySQL 线协议、Redis RESP2 协议、标准 SQL
- 三种存储模式 —— 纯内存、混合(LRU + 异步刷盘)、磁盘持久化
你 npm install jsql-neo 一把装完,要速度有 Native,要便携有 WASM,要兼容有 MySQL/Redis 协议——不用再选,全给你。
🚀 30 秒上手
WASM 模式(零原生依赖,开箱即用)
const { JSQL } = require('jsql-neo');
const db = new JSQL();
await db.start();
await db.createTable('users', {
name: { type: 'string' },
age: { type: 'integer' }
});
const [id] = await db.insert('users', { name: 'Alice', age: 30 });
const user = await db.findById('users', id);
// → { id: 1, fields: { name: 'Alice', age: 30 }, created_at: '...', updated_at: '...' }
await db.stop();
Native 模式(Rust N-API,最快路径)
const jsql = require('jsql-neo');
const db = new jsql.NativeJSQL({ path: './data', mode: 'hybrid' });
await db.start();
await jsql.executeSQL(db, 'CREATE TABLE users (id INTEGER PRIMARY KEY AUTO_INCREMENT, name STRING, age INTEGER)');
await jsql.executeSQL(db, "INSERT INTO users (name, age) VALUES ('Alice', 30), ('Bob', 25)");
const rows = await jsql.executeSQL(db, 'SELECT name, age FROM users WHERE age > 26 ORDER BY age DESC');
// → [["Alice", 30]]
await db.stop();
Pure JS 模式(本地 JSON 文件,SQLite 风格)
const { Database } = require('jsql-neo');
const db = new Database('/tmp/mydb.json');
const users = db.createTable('users', {
id: { type: 'integer', autoIncrement: true, primaryKey: true },
name: { type: 'string', length: 32 },
age: { type: 'integer' }
});
const ids = users.insertMany([{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }]);
users.updateById(ids[0], { age: 31 });
db.save();
🏗️ 架构总览
┌─────────────────────────── JSQL-NEO ───────────────────────────┐
│ │
│ Node.js ──┤ Native (Rust N-API) ⚡ 最快路径,零依赖 │
│ Node.js ──┤ WASM (Rust → wasm) 🧩 可移植,无原生插件 │
│ Browser ──┤ WASM (+ IndexedDB) 🌐 浏览器内完整 SQL 引擎 │
│ Anywhere ─┤ Pure JS (JSON file) 📦 SQLite 风格本地持久化 │
│ │
│ ├── 🐘 MySQL 协议 ──► Sequelize / Knex / TypeORM / mysql2 │
│ ├── 🐇 Redis 协议 ──► ioredis / node-redis / redis-cli │
│ ├── 🌐 HTTP API ──► 内置 Web UI + 管理接口 │
│ └── 📝 SQL 引擎 ──► CREATE / SELECT / JOIN / 聚合 │
└────────────────────────────────────────────────────────────────────┘
⚡ 三引擎性能对比
100,000 行数据,Linux x64,Node 24:
| 引擎 | 插入速度 | 点查询 (500×) | 范围查询 (500×) | 总耗时 |
|---|---|---|---|---|
| Native (Rust N-API) | 0.66M/s | 930ms | 685ms | 1.77s 🏆 |
| better-sqlite3 (WAL) | 0.40M/s | 3258ms | 149ms | 3.66s |
| sql.js (WASM SQLite) | 0.30M/s | 5852ms | 366ms | 6.57s |
| Pure JS 引擎 | 0.38M/s | 11278ms | 18138ms | 29.7s |
约 2× faster than better-sqlite3,约 17× faster than 纯 JS 引擎。
独立实测验证(沙盒环境,Node v20,AMD EPYC)
| 测试条件 | 实测结果 |
|---|---|
Native + mode:'disk' + 10 万行批量插入 |
1,932,233 rows/s |
Native + mode:'memory' + 10 万行批量插入 |
1,067,380 rows/s |
| Native + 1 万行点查询 | 184,064 qps |
| WASM + 1 万行点查询 | 108,261 qps |
✅ 数据行数校验全部通过,无丢失。
🐘 说 MySQL 协议
JSQL-neo 内置 MySQL 线协议服务器,不需要任何插件或中间件,标准 MySQL 客户端直接连:
jsql serve -p 3306 --data-dir ./data
mysql -h 127.0.0.1 -P 3306 -u root
已验证兼容:
| ORM / 驱动 | 版本 | 结果 |
|---|---|---|
| Sequelize | v6 | ✅ 10/10 — connect, authenticate, sync, create, bulkCreate, find, count, update, destroy, MAX() |
| Knex | v3 | ✅ 9/9 — schema builder, insert, select, where + orderBy, count, update, delete, raw SQL |
| TypeORM | v0.3 | ✅ 8/8 — initialize, synchronize, save, findOne, find, count, update, delete |
| mysql2 | latest | ✅ prepared statements, binary protocol, SHOW COLUMNS / INDEX / VARIABLES |
支持的 SQL 特性:
CREATE / SELECT / INSERT / UPDATE / DELETE / JOIN / GROUP BY / HAVING / ORDER BY / LIMIT / OFFSETBEGIN / COMMIT / ROLLBACK事务- 标量函数:
VERSION() / NOW() / CONCAT() / IFNULL() / COALESCE() / UPPER() / LOWER() / LENGTH() / ROUND() - 系统变量:
@@version / @@sql_mode,支持SET修改 - MySQL DDL 风格:
int unsigned / AUTO_INCREMENT / ENGINE=InnoDB / DEFAULT CHARSET
🐇 说 Redis 协议
内置 RESP2 服务器,兼容 ioredis / node-redis / redis-cli:
jsql redis -p 6379 --data-dir ./redis-data
redis-cli SET hello world
支持命令:
| 类别 | 命令 |
|---|---|
| 通用 | PING / ECHO / EXISTS / DEL / KEYS / TYPE / DBSIZE / FLUSHALL / FLUSHDB / SELECT / INFO / AUTH / QUIT |
| 字符串 | SET / GET / SETNX / INCR / DECR / INCRBY / DECRBY / APPEND / STRLEN |
| 哈希 | HSET / HGET / HGETALL / HDEL / HEXISTS / HLEN / HKEYS / HVALS |
| 列表 | LPUSH / RPUSH / LPOP / RPOP / LLEN / LRANGE / LINDEX / LREM |
| 集合 | SADD / SREM / SMEMBERS / SISMEMBER / SCARD |
| TTL | EXPIRE / TTL / PERSIST |
持久化:快照写入 data.rdb.json,防抖 500ms + 关闭时强制刷盘。
🗃️ 存储模式
| 模式 | 行为 | 适用场景 |
|---|---|---|
memory |
纯内存,最大速度,不落盘 | 缓存、临时计算、测试 |
hybrid |
内存优先 + 异步增量刷盘 + LRU 淘汰 | 默认推荐,兼顾速度与持久化 |
disk |
50ms 刷盘间隔,内存作读写缓存 | 数据安全性优先 |
const db = new jsql.NativeJSQL({
path: '/var/lib/jsql',
mode: 'hybrid', // 'memory' | 'hybrid' | 'disk'
memReserveMB: 512, // LRU 淘汰前的 RAM 预留
flushInterval: 200 // 异步刷盘频率(ms)
});
- 原子写入(tmp + rename)
- 每表独立文件
- WAL + 快照崩溃恢复(HTTP 引擎)
🧰 内置工具箱
CLI 命令
| 命令 | 功能 |
|---|---|
jsql serve |
前台运行 MySQL 兼容服务器 |
jsql server start/stop/status |
后台守护进程(pid 控制) |
jsql redis |
运行 Redis 兼容服务器 |
jsql ui -p 8080 |
启动内置 Web 管理控制台 → http://localhost:8080 |
jsql import <file> |
导入 mysqldump / JSON / CSV |
jsql export <table> |
导出 JSON / CSV |
jsql bench |
插入 + 查询基准测试 |
jsql mod |
插件注册表(启用/禁用/列表) |
jsql version |
打印版本号 |
Web UI
零依赖的内置管理控制台:浏览数据库和表、在浏览器里跑 SQL、表格化展示结果。适合开发工具、管理面板、Demo 展示。
迁移工具
const { importDumpFile, exportToFile, importFromCSV, exportAllToJSON } = require('jsql-neo');
await importDumpFile(db, './backup.sql', { strict: true }); // 真实 mysqldump 格式
await exportToFile(db, 'users', './users.csv'); // CSV 往返
浏览器 Playground
examples/playground/ 是自包含的 SQL 沙盒——整个引擎在浏览器中运行(WASM + IndexedDB 持久化,无需服务器):
cd examples/playground && npm install && npm run dev
📋 API 一览
| 方法 | Native | WASM | Pure JS | 说明 |
|---|---|---|---|---|
createTable(name, schema) |
✅ | ✅ | ✅ | 定义带类型字段的表 |
insert(table, data) |
✅ | ✅ | ✅ | 插入行/批量,返回 ID |
findById(table, id) |
✅ | ✅ | ✅ | O(1) 主键哈希查找 |
find(table, filter) |
✅ | ✅ | ✅ | B-Tree 索引过滤查询 |
count(table) |
✅ | ✅ | ✅ | 行数统计 |
updateById(table, id, data) |
✅ | ✅ | ✅ | O(1) 主键更新 |
removeById(table, id) |
✅ | ✅ | ✅ | O(1) 主键删除 |
dropTable(name) |
✅ | ✅ | ✅ | 删除表 |
executeSQL(db, sql, params) |
✅ | ✅ | ✅ | 完整 SQL 引擎 + 预处理语句 |
三种引擎共享同一套异步 API,写一次代码,任意引擎运行。
🔧 字段类型与索引
{
type: 'string' | 'integer' | 'float' | 'boolean',
primaryKey: true, // 主键(自动建 B-Tree 索引)
autoIncrement: true, // 整数主键自增
length: 32, // 字符串最大长度
default: 'value', // 默认值
nullable: true // 允许 NULL
}
- 主键:自动 O(1) 哈希索引(FxHashMap / Map)
- 唯一键 / 范围查询:自动 B-Tree 索引,复杂度从 O(n) 降至 O(log n)
- 大表 JOIN:数据量 > 100 行自动使用哈希 JOIN(O(n+m)),小表退化为嵌套循环
🔌 插件系统
JSQL-neo 提供插件注册表(jsql mod CLI),支持通过插件扩展引擎功能。插件系统与 VM 沙箱隔离运行。
📦 安装
npm install jsql-neo
| 指标 | 数值 |
|---|---|
| 运行时依赖 | 0 个 |
| 包大小 | ~11.7 MB(含 Rust 原生模块 + WASM) |
| Node.js 支持 | 18 / 20 / 22 |
| TypeScript | 完整声明文件(index.d.ts,tsc --strict 验证通过) |
| CI | GitHub Actions,Node 18/20/22 + ORM 兼容测试 |
| 周下载量 | ~4,182 |
| 当前版本 | 4.5.2 |
| 许可证 | Apache-2.0(npm)/ MIT(GitHub README 标注不一致 ⚠️) |
🧪 测试
npm test # 零依赖 SQL 引擎冒烟测试
npm run test:orms # ORM 兼容性测试(先启动 examples/orms/start-server.js)
CI 配置(.github/workflows/ci.yml):Node 18/20/22 引擎冒烟测试 + 完整 ORM 兼容性任务。
🎯 适用场景
| 场景 | 推荐引擎 | 推荐模式 |
|---|---|---|
| 生产环境热路径 | Native (Rust N-API) | hybrid / disk |
| 边缘计算 / Serverless | WASM | memory |
| 浏览器内应用 | WASM + IndexedDB | memory |
| 零原生部署(共享主机) | Pure JS | disk |
| 开发 / Demo / 管理工具 | 任意 + Web UI | memory |
| 替代 Redis 做本地缓存 | Native + Redis 协议 | memory |
| 替代 SQLite 做嵌入式存储 | Native | hybrid |
⚠️ 当前已知问题
| 问题 | 严重程度 | 说明 |
|---|---|---|
| 版本号节奏过快 | 🟡 中 | 17 天从 1.0.0 到 4.5.2,3 次 major 跃迁,核心 API 未断代 |
| License 不一致 | 🟡 中 | npm 标 Apache-2.0,GitHub README 写 MIT |
| 测试覆盖不足 | 🟡 中 | 冒烟测试通过,但无 sqllogictest / Jepsen 级别正确性验证 |
| 社区生态为零 | 🟠 低 | 0 followers,dependents 为 0,无生产用例背书 |
wrct-neo npm 404 |
🔴 高(供应链) | minep2p 依赖此包但 npm 上不存在,新环境安装会断裂 |
| 年龄 / 身份未验证 | ⚪ 信息 | "10 岁 CEO"为自称,无第三方认证 |
📊 项目信息
| 项目 | 信息 |
|---|---|
| 作者 | vexify-root(vexify-org 组织) |
| 仓库 | https://github.com/vexify-org/JSQL-neo |
| npm | https://www.npmjs.com/package/jsql-neo |
| 文档站 | https://vexify-org.github.io/JSQL-neo/ |
| 许可证 | Apache-2.0 / MIT(见上方不一致说明) |
| 首次发布 | 2026-07-21 |
| 最新版本 | 4.5.2(2026-08-07) |
💬 总结
JSQL-neo 是一个有硬核技术的嵌入式数据库引擎——Rust 核心跑出百万级行 / 秒的批量插入,三引擎共享 API 降低了切换成本,MySQL + Redis 双协议兼容让它可以无缝替换现有基础设施的本地部分。
它不是 PPT 数据库,是真正能装、能跑、能测、有 benchmark 的东西。
但它也还没到 "权威" 级别——版本节奏混乱、测试覆盖偏浅、社区生态为零、供应链有断裂风险。距离生产级信任,还差 CI/CD 硬化、第三方安全审计、真实采用案例和社区治理这四步。
如果你想要一个 "本地能跑、协议兼容、速度够快" 的嵌入式数据库做开发或边缘场景,JSQL-neo 值得一试。如果你要的是 "经过十年生产验证" 的信任,那它还没到那个年纪。
JSQL-NEO: Rust-powered. Protocol-native. One package. Powered By Vexify