JSQL-NEO

One engine to rule them all — a Rust-powered embedded database that speaks your language: MySQL, PostgreSQL, MongoDB, Redis, SQL, TypeScript, and the browser.

v6.5.29 — stable release · github.com/vexify-org/JSQL-neo · jsql.vexify.top

Demo

A real jsql tui session (v6.5.25): 64-bit integer precision, joins, NULL semantics, and savepoint rollback — all in one in-memory engine, rendered on a dark background.

MP4 version · asciinema recording

🚀 Quick Start

One-line install

curl -fsSL jsql.vexify.top/setup | bash

Or in PowerShell (Windows):

irm jsql.vexify.top/setup | iex

npm install

npm install jsql-neo

JSQL-NEO is a Rust-powered embedded database with a single runtime dependency (@vexify-org/yaggs, used only by the jsql CLI argument parser) — no native libs to compile, no system deps to install. It runs in Node.js, CLI, Web UI, and the browser (WASM).

• Four wire protocols on one port — jsql serve accepts MySQL, PostgreSQL, MongoDB and Redis clients; mysql2, pg, mongodb and ioredis connect directly
• Nearly dependency-free — only @vexify-org/yaggs (CLI arg parsing); no native libs to compile, no system deps to install
• Three engines, same API — native (Rust N-API), wasm (same Rust core), js (pure JS)
• O(1) primary-key lookups and updates — hash index, no full-table scan; unindexed filters run in Rust

Wire protocols — MySQL, PostgreSQL, MongoDB and Redis share a single listener (jsql serve, default port 3306). The server sniffs the first packet of each connection and hands it to the matching protocol handler. MySQL / PostgreSQL / MongoDB read the same Database engine (same tables), Redis keeps its own key namespace. Verified with mysql2, pg, mongodb (driver 7.x) and ioredis; pass --mysql-only to serve the MySQL protocol alone.

Feature Overview

JSQL-NEO: MySQL + PostgreSQL + MongoDB + Redis + SQL
  One port, one engine, all protocols — Node.js / WASM / CLI / Web UI

| Feature | Detail | |---|---| | Rust Core | N-API native addon — O(1) primary-key point lookups, binary bulk inserts, Rust-side row filtering | | WASM Build | Same engine runs in Node.js and any browser | | MySQL | mysql2, Sequelize, Knex, TypeORM — just work | | PostgreSQL | pg, psql, pgAdmin — SCRAM-SHA-256, JSONB, ILIKE | | MongoDB | mongodb, mongosh, Compass — OP_MSG, BSON, aggregation | | Redis | ioredis, redis-cli — all data types + TTL | | One Port | Protocol sniffing routes all four clients to the same data | | Zero-Dep TUI | jsql tui — line editing, history, Tab, CJK tables | | Web UI | Management console + HTTP API with no frontend framework | | WASM | Full engine in browser, no server needed |

Quick Start

Install

npm install jsql-neo

Three lines of code

const { Database, executeSQL } = require('jsql-neo');

const db = new Database(':memory:');
await executeSQL(db, "CREATE TABLE users (id INT PRIMARY KEY AUTO_INCREMENT, name TEXT)");
await executeSQL(db, "INSERT INTO users (name) VALUES ('Alice')");
const { rows } = await executeSQL(db, "SELECT * FROM users");
console.log(rows); // [[1, 'Alice']]
db.stop();

Wire protocol server

jsql serve --port 3306 --data-dir ./data

All four protocols share the same port:

# MySQL clients (mysql CLI, mysql2, DBeaver, DataGrip …)
mysql -h 127.0.0.1 -P 3306 -u root

# PostgreSQL clients (psql, pg, pgAdmin …)
psql "host=127.0.0.1 port=3306 user=postgres dbname=app"

# MongoDB clients (mongosh, mongodb driver, Compass …)
mongosh "mongodb://127.0.0.1:3306/app?directConnection=true"

# Redis clients (redis-cli, ioredis …)
redis-cli -h 127.0.0.1 -p 3306 PING

Pass --mysql-only to serve the MySQL wire protocol alone.

Browser / WASM

import init, { JSQL } from 'jsql-neo/wasm/browser.mjs';
await init();
const db = new JSQL();
// same API as the Node.js native client

🦀 NativeJSQL

Pure Rust native bindings — the highest-performance way to run JSQL-NEO:

• Low abstraction overhead — direct calls into the Rust core
• Batch operations — ~700k rows/sec measured on 200k rows (INSERT in 5k batches)
• Automatic memory management with smart caching

Install:

npm install jsql-neo

Usage:

const { NativeJSQL } = require('jsql-neo');
const db = new NativeJSQL();          // :memory: — persist by passing a path
await db.start();

Storage modes

| Mode | Usage | Use Case | |---|---|---| | Memory | new Database(':memory:') | Testing, caching | | Disk | new Database('./data/app') | Production persistence | | Hybrid | new Database('./data', { autoSave: true, saveInterval: 3000 }) | Performance + durability |

Query results

db.query() / executeSQL() return one result in three shapes:

const r = await db.query('SELECT city, COUNT(*) AS c FROM users GROUP BY city');
r.columns   // ['city', 'c']
r.rows      // [['LA', 1], ['NY', 2]]
r.raw       // [{ city: 'LA', c: 1 }, { city: 'NY', c: 2 }]

raw is the object form of rows: its keys are exactly columns, and that includes computed, aggregate and scalar-subquery columns. It is not the pre-projection source row. For SELECT results raw.length === rows.length always holds; non-SELECT statements may omit raw.

To check which native addon this installation is actually using:

• jsql native status — tag/version match (0 = OK, 1 = mismatch or unverified)
• jsql native verify — re-hashes the .node on disk against the checksum recorded at install time, so a swapped or corrupted binary is caught too. --json prints a structured result for CI. States: OK / MISMATCH / CORRUPT / MISSING / UNVERIFIED / UNREADABLE.
• jsql native refresh — re-fetches a checksum-verified addon

✨ XQL 集成

用 XQL 查询 JSQL 表：把 SQL 直接接到文档上， 支持等值 hash 索引与范围 range 索引，速度不低于手写 JS 循环，并支持管道式语法。

const { NativeJSQL } = require('jsql-neo');
const db = new NativeJSQL();
await db.start();

db.use(require('jsql-neo/lib/plugins').xql());

// 标准 SQL
const rows = await db.xql('SELECT name FROM users WHERE age > 18 ORDER BY name');
// 管道式（同样的语义）
const pipe = await db.xql('FROM users |> WHERE age > 18 |> SELECT name |> ORDER BY name');

// 索引：等值 → hash 索引 O(1)，范围 → 有序索引 O(log n + k)
db.xqlIndex('users', 'id');
db.xqlIndex('users', 'score', 'range');

写入（INSERT / UPDATE / DELETE）后 XQL 缓存自动失效、下次查询重建；XQL 只读， 不做写回——数据的唯一权威仍是 JSQL 引擎。详见 PLUGINS.md。

📖 Documentation

Detailed docs live in doc/ — click to read.

| Document | Description | |---|---| | doc/index.md | Overview, architecture, concepts | | doc/why.md | Why JSQL-NEO exists, design philosophy | | doc/quick-start.md | Install, API basics, Web UI | | doc/multiprotocol.md | One-port multi-protocol server, sniffing logic | | doc/mysql.md | MySQL protocol: auth, system vars, syntax, FAQ | | doc/postgresql.md | PostgreSQL protocol: SCRAM-SHA-256, wire v3, SQLSTATE | | doc/mongodb.md | MongoDB protocol: BSON, commands, operators, aggregation | | doc/redis.md | Redis protocol: data types, commands, TTL, snapshots | | doc/api-reference.md | Full API: Database, executeSQL, config options | | doc/sql-reference.md | SQL: statements, data types, functions, operators, indexes | | doc/cli.md | CLI: jsql tui, jsql serve, jsql ui | | doc/changelog.md | Release notes |

🤝 Contributing & License

Apache-2.0 License — contributions welcome!

• GitHub: vexify-org/JSQL-neo
• Issues: Open an issue
• PRs: Fork → branch → PR — thank you!
• Contributing: CONTRIBUTING.md
• Dev container: jsql-neo/devbox — reproducible dev environment (Docker/devcontainer)
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md — please report vulnerabilities privately