JSQL-neo 进度介绍
Rust 驱动的嵌入式数据库，一个 npm 包装三种引擎、三种协议、三种存储模式。
📦 GitHub: https://github.com/vexify-org/JSQL-neo 📦 npm: https://www.npmjs.com/package/jsql-neo 🌐 文档站: https://vexify-org.github.io/JSQL-neo/ 📄 License: Apache-2.0
📌 当前版本：v5.2.1（2026-08-11 实测）
| 指标 | 数值 |
|---|---|
| 最新版本 | 5.2.1 |
| 首次发布 | 2026-07-21 |
| 版本演进速度 | 17 天从 1.0.0 → 5.2.1（极快） |
| 运行时依赖 | 1 个 |
| Node.js 支持 | 18 / 20 / 22 |
| TypeScript | 完整声明文件（index.d.ts，tsc --strict 通过） |
| CI | GitHub Actions，Node 18/20/22 + ORM 兼容测试 |
| 许可证 | Apache-2.0 |
🚀 30 秒上手
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');
// → [["Carol",35],["Alice",30]]
await db.stop();
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 });
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 }]);
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 / 聚合 │
└────────────────────────────────────────────────────────────────────┘
⚡ 性能实测（沙盒环境验证，2026-08-11）
官方 Benchmark（100K 行，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 引擎。
沙盒实测（v5.2.1，Node v20，AMD EPYC）
| 测试项 | 结果 |
|---|---|
| 批量插入 10,001 行（Native + memory 模式） | 70ms → ~143K rows/s |
| 批量插入 50,000 行（Native + memory 模式） | 326ms → ~153K rows/s |
| 1000 次点查询 | 31226ms → ~32 QPS（含 JS 桥接开销） |
| CREATE / INSERT / SELECT / UPDATE / DELETE | ✅ 全部通过 |
| JOIN（2 表 INNER JOIN） | ✅ 通过 |
| 事务 BEGIN / COMMIT / ROLLBACK | ✅ 通过 |
| 聚合 COUNT / SUM | ✅ 通过 |
🐘 MySQL 协议兼容
内置 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 |
支持的 MySQL 特性：
CREATE / SELECT / INSERT / UPDATE / DELETE / JOIN / GROUP BY / HAVING / ORDER BY / LIMIT / OFFSET- 事务
BEGIN / 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）
});
🧰 内置工具箱
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、表格化展示结果。
迁移工具
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)），小表退化为嵌套循环
📦 安装
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 兼容测试 |
🧪 测试
npm test # 零依赖 SQL 引擎冒烟测试
npm run test:orms # ORM 兼容性测试（先启动 examples/orms/start-server.js）
npm run test:coverage # c8 覆盖率套件（57 个集成断言）
CI 配置（.github/workflows/ci.yml）：Node 18/20/22 引擎冒烟测试 + 完整 ORM 兼容性任务。
📜 版本演进时间线
| 版本 | 日期 | 里程碑 |
|---|---|---|
| v1.0.0 | 2026-07-21 | 首次发布，Pure JS 引擎 + 基础 SQL |
| v2.0.0 | 2026-07-23 | B-Tree 索引、哈希 JOIN、WAL 日志、事务隔离、MySQL 风格错误码 |
| v3.x.x-beta | 2026-07-25 ~ 08-01 | 插件系统、批量操作、MySQL 兼容层、beta 迭代 |
| v4.0.0 | 2026-08-01 | Native (Rust N-API) 引擎上线、hybrid/disk 存储模式、LICENSE 完善 |
| v4.4.1 | 2026-08-06 | MySQL/Redis 双协议、Web UI、CLI 工具、迁移工具、TS 类型、Benchmark、浏览器 Playground、CI |
| v4.4.2 | 2026-08-06 | 覆盖率套件、exports 细化、nativesrc 同步、LPUSH 顺序修复、splitStatements 修复 |
| v4.5.x ~ v5.2.1 | 2026-08-07 ~ 08-11 | exports 子路径解析修复、持续 bug 修复与细化 |
🎯 适用场景
| 场景 | 推荐引擎 | 推荐模式 |
|---|---|---|
| 生产环境热路径 | 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 |
💬 总结
JSQL-neo 是一个有硬核技术的嵌入式数据库引擎——Rust 核心跑出百万级行 / 秒的批量插入，三引擎共享 API 降低了切换成本，MySQL + Redis 双协议兼容让它可以无缝替换现有基础设施的本地部分。
它不是 PPT 数据库，是真正能
npm install、能跑、能测、有 benchmark 的东西。但它也还没到 "权威" 级别——版本节奏混乱、测试覆盖偏浅、社区生态为零。距离生产级信任，还差 CI/CD 硬化、第三方安全审计、真实采用案例和社区治理这四步。
如果你想要一个 "本地能跑、协议兼容、速度够快" 的嵌入式数据库做开发或边缘场景，JSQL-neo 值得一试。如果你要的是 "经过十年生产验证" 的信任，那它还没到那个年纪。
JSQL-NEO: Rust-powered. Protocol-native. One package.