@wowoengine/sawitdb 2.4.0 → 2.6.0

package/README.md

@@ -5,6 +5,7 @@
 <div align="center">
 
 [![Docs](https://img.shields.io/badge/Docs-Read%20Now-blue?style=for-the-badge&logo=googledocs)](https://wowoengine.github.io/SawitDB/)
+[![NPM](https://img.shields.io/npm/v/@wowoengine/sawitdb?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@wowoengine/sawitdb)
 [![Go Version](https://img.shields.io/badge/Go%20Version-Visit%20Repo-cyan?style=for-the-badge&logo=go)](https://github.com/WowoEngine/SawitDB-Go)
 [![Changelog](https://img.shields.io/badge/Changelog-Read%20Updates-orange?style=for-the-badge&logo=github)](CHANGELOG.md)
 
@@ -13,9 +14,9 @@
 
 **SawitDB** is a unique database solution stored in `.sawit` binary files.
 
-The system features a custom **Paged Heap File** architecture similar to SQLite, using fixed-size 4KB pages to ensure efficient memory usage. What differentiates SawitDB is its unique **Agricultural Query Language (AQL)**, which replaces standard SQL keywords with Indonesian farming terminology.
+The system features a custom **Hybrid Paged Architecture** similar to SQLite but supercharged with **Object Caching**, using fixed-size 4KB pages to ensure efficient memory usage and near-instant access. What differentiates SawitDB is its unique **Agricultural Query Language (AQL)**, which replaces standard SQL keywords with Indonesian farming terminology.
 
-**Now with Network Edition!** Connect via TCP using `sawitdb://` protocol similar to MongoDB.
+**Now available on NPM!** Connect via TCP using `sawitdb://` protocol.
 
 **🚨 Emergency: Aceh Flood Relief**
 Please support our brothers and sisters in Aceh.
@@ -26,14 +27,18 @@ Please support our brothers and sisters in Aceh.
 
 ## Features
 
-- **Paged Architecture**: Data is stored in 4096-byte binary pages. The engine does not load the entire database into memory.
+- **Hybrid Paged Architecture**: Data is stored in 4096-byte binary pages, but hot data is cached as native Objects for zero-copy reads.
 - **Single File Storage**: All data, schema, and indexes are stored in a single `.sawit` file.
 - **High Stability**: Uses 4KB atomic pages. More stable than a coalition government.
 - **Data Integrity (Anti-Korupsi)**: Implements strict `fsync` protocols. Data cannot be "corrupted" or "disappear" mysteriously like social aid funds (Bansos). No "Sunat Massal" here.
+- **Crash Recovery**: Uses **Write-Ahead Logging (WAL)**. Guarantees data always returns after a crash. Unlike a fugitive (Buronan) who is "hard to find".
 - **Zero Bureaucracy (Zero Deps)**: Built entirely with standard Node.js. No unnecessary "Vendor Pengadaan" or "Mark-up Anggaran".
 - **Transparansi**: Query language is clear. No "Pasal Karet" (Ambiguous Laws) or "Rapat Tertutup" in 5-star hotels.
 - **Speed**: Faster than printing an e-KTP at the Kelurahan.
 - **Network Support (NEW)**: Client-Server architecture with Multi-database support and Authentication.
+- **True Multi-Threading (NEW)**: Worker Pool architecture separates IO (Main Thread) from CPU (Worker Threads).
+- **Advanced SQL (NEW)**: Support for `JOIN` (Left/Right/Full/Cross), `JAVING`, `DISTINCT`, and more.
+- **NPM Support (NEW)**: Install via `npm install @wowoengine/sawitdb`.
 
 ## Filosofi
 
@@ -45,38 +50,48 @@ SawitDB is built with the spirit of "Data Sovereignty". We believe a reliable da
 
 ## File List
 
-- `src/WowoEngine.js`: Core Database Engine (Class: `SawitDB`).
+- `src/WowoEngine.js`: Core Database Engine Entry Point.
+- `src/SawitServer.js`: Server Class.
+- `src/SawitClient.js`: Client Class.
+- `src/modules/`: Core modules (QueryParser, BTreeIndex, WAL, Pager).
+- `src/services/`: Logic services (TableManager, IndexManager, QueryExecutor).
+- `src/services/executors/`: Specific query executors (Select, Insert, Update, Delete, Aggregate).
+- `src/services/logic/`: Complex logic handlers (JoinProcessor, ConditionEvaluator).
+- `src/server/`: Server components (AuthManager, RequestRouter, DatabaseRegistry).
 - `bin/sawit-server.js`: Server executable.
-- `cli/local.js`: Interactive CLI tool (Local).
-- `cli/remote.js`: Interactive CLI tool (Network).
-- [CHANGELOG.md](CHANGELOG.md): Version history and release notes.
-- `examples/`: Sample scripts.
+- `cli/`: Command Line Interface tools (local, remote, test, bench).
+- [CHANGELOG.md](CHANGELOG.md): Version history.
+- [docs/DB Event](docs/DB Event.md): Database Event Documentation.
 
 ## Installation
 
-Ensure you have Node.js installed. Clone the repository.
+Install via NPM:
 
 ```bash
-# Clone
-git clone https://github.com/WowoEngine/SawitDB.git
+npm install @wowoengine/sawitdb
 ```
 
-## Quick Start (Network Edition)
+## Quick Start
 
 ### 1. Start the Server
 ```bash
-node src/SawitServer.js
+node bin/sawit-server.js
+# Or with Cluster Mode enabled in .env
 ```
 The server will start on `0.0.0.0:7878` by default.
 
 ### 2. Connect with Client
-Use [SawitClient](#client-api) or any interactive session.
+You can use the built-in CLI tool:
+```bash
+node cli/remote.js
+```
+Or use the `SawitClient` class in your Node.js application.
 
 ---
 
 ## Dual Syntax Support
 
-SawitDB 2.3 introduces the **Generic Syntax** alongside the classic **Agricultural Query Language (AQL)**, making it easier for developers familiar with standard SQL to adopt.
+SawitDB introduces the **Generic Syntax** alongside the classic **Agricultural Query Language (AQL)**, making it easier for developers familiar with standard SQL to adopt.
 
 | Operation | Agricultural Query Language (AQL) | Generic SQL (Standard) |
 | :--- | :--- | :--- |
@@ -177,27 +192,61 @@ CREATE INDEX ON [table] ([field])
 ```sql
 HITUNG COUNT(*) DARI [table]
 HITUNG AVG(price) DARI [products] KELOMPOK [category]
--- Generic Keyword Alias
-SELECT AVG(price) FROM [products] GROUP BY [category] (Coming Soon)
+-- With HAVING clause
+HITUNG COUNT(*) DARI sales GROUP BY region HAVING count > 5
+```
+
+#### DISTINCT
+```sql
+SELECT DISTINCT category FROM products
+-- Returns only unique values
+```
+
+#### JOIN Types
+```sql
+-- INNER JOIN (default)
+SELECT * FROM orders JOIN customers ON orders.customer_id = customers.id
+
+-- LEFT OUTER JOIN
+SELECT * FROM employees LEFT JOIN departments ON employees.dept_id = departments.id
+
+-- RIGHT OUTER JOIN
+SELECT * FROM employees RIGHT JOIN departments ON employees.dept_id = departments.id
+
+-- CROSS JOIN (Cartesian product)
+SELECT * FROM colors CROSS JOIN sizes
+```
+
+#### EXPLAIN Query Plan
+```sql
+EXPLAIN SELECT * FROM users WHERE id = 5
+-- Returns execution plan: scan type, index usage, join methods
 ```
 
 ## Architecture Details
 
-- **Modular Codebase**: Engine logic separated into `src/modules/` (`Pager.js`, `QueryParser.js`, `BTreeIndex.js`) for better maintainability.
-- **Page 0 (Master Page)**: Contains header and Table Directory.
-- **Data & Indexes**: Stored in 4KB atomic pages.
+- **Worker Pool (Multi-threaded)**:
+    - **Main Thread**: Handles strictly I/O (Networking, Protocol Parsing).
+    - **Worker Threads**: Execute queries in parallel using `Least-Busy` Load Balancing.
+    - **Fault Tolerance**: Automatic worker healing and stuck-query rejection.
+- **Storage Engine**:
+    - **Hybrid Paging**: 4KB binary pages with In-Memory Object Cache for hot data.
+    - **WAL (Write-Ahead Log)**: Ensures ACID properties and crash recovery.
+    - **B-Tree Indexing**: O(log n) lookups for high performance.
+- **Modular Codebase**: Core logic separated into `src/modules/` (`Pager.js`, `ThreadPool.js`, `BTreeIndex.js`).
 
 ## Benchmark Performance
 Test Environment: Single Thread, Windows Node.js (Local NVMe)
 
 | Operation | Ops/Sec | Latency (avg) |
 |-----------|---------|---------------|
-| **INSERT** | ~3,125 | 0.32 ms |
-| **SELECT (PK Index)** | ~3,846 | 0.26 ms |
-| **SELECT (Scan)** | ~4,762 | 0.21 ms |
-| **UPDATE** | ~3,571 | 0.28 ms |
+| **INSERT** | ~22,000 | 0.045 ms |
+| **SELECT (PK Index)** | **~247,288** | 0.004 ms |
+| **SELECT (Scan)** | ~13,200 (10k rows) | 0.075 ms |
+| **UPDATE (Indexed)** | ~11,000 | 0.090 ms |
+| **DELETE (Indexed)** | ~19,000 | 0.052 ms |
 
-*Note: Hasil dapat bervariasi tergantung hardware.*
+*Note: Hasil diatas adalah benchmark Internal (Engine-only). Untuk Network Benchmark (Cluster Mode), TPS berkisar ~20.000 (overhead jaringan).*
 
 ## Full Feature Comparison
 
@@ -212,12 +261,23 @@ Test Environment: Single Thread, Windows Node.js (Local NVMe)
 | **Drop Table** | `BAKAR LAHAN [table]` | `DROP TABLE [table]` | Deletes table & data |
 | **Insert** | `TANAM KE [table] ... BIBIT (...)` | `INSERT INTO [table] (...) VALUES (...)` | Auto-ID if omitted |
 | **Select** | `PANEN ... DARI [table] DIMANA ...` | `SELECT ... FROM [table] WHERE ...` | Supports Projection |
+| **Ordering** | `URUTKAN BERDASARKAN [col] [ASC/DESC/NAIK/TURUN]` | `ORDER BY [col] [ASC/DESC]` | Sort results |
+| **Limit** | `HANYA [n]` | `LIMIT [n]` | Limit rows |
+| **Offset** | `MULAI DARI [n]` | `OFFSET [n]` | Skip rows |
 | **Update** | `PUPUK [table] DENGAN ... DIMANA ...` | `UPDATE [table] SET ... WHERE ...` | Atomic update |
 | **Delete** | `GUSUR DARI [table] DIMANA ...` | `DELETE FROM [table] WHERE ...` | Row-level deletion |
 | **Index** | `INDEKS [table] PADA [field]` | `CREATE INDEX ON [table] (field)` | B-Tree Indexing |
 | **Count** | `HITUNG COUNT(*) DARI [table]` | `SELECT COUNT(*) FROM [table]` (via HITUNG) | Aggregation |
 | **Sum** | `HITUNG SUM(col) DARI [table]` | `SELECT SUM(col) FROM [table]` (via HITUNG) | Aggregation |
 | **Average** | `HITUNG AVG(col) DARI [table]` | `SELECT AVG(col) FROM [table]` (via HITUNG) | Aggregation |
+| **Min/Max** | `HITUNG MIN(col) DARI [table]` | `SELECT MIN(col) FROM [table]` (via HITUNG) | Aggregation |
+| **Grouping**| `KELOMPOK [col]` | `GROUP BY [col]` | Group results |
+| **DISTINCT** | `PANEN DISTINCT col DARI [table]` | `SELECT DISTINCT col FROM [table]` | Unique rows |
+| **LEFT JOIN** | `GABUNG KIRI [table] PADA ...` | `LEFT JOIN [table] ON ...` | Outer join |
+| **RIGHT JOIN** | `GABUNG KANAN [table] PADA ...` | `RIGHT JOIN [table] ON ...` | Outer join |
+| **CROSS JOIN** | `GABUNG SILANG [table]` | `CROSS JOIN [table]` | Cartesian product |
+| **HAVING** | `DENGAN SYARAT count > 5` | `HAVING count > 5` | Filter groups |
+| **EXPLAIN** | `JELASKAN SELECT ...` | `EXPLAIN SELECT ...` | Query plan |
 
 ### Supported Operators Table
 
@@ -231,6 +291,7 @@ Test Environment: Single Thread, Windows Node.js (Local NVMe)
 | **Range** | `BETWEEN 1000 AND 5000` | Inclusive range check |
 | **Null** | `IS NULL` | Check if field is empty/null |
 | **Not Null** | `IS NOT NULL` | Check if field has value |
+| **Distinct** | `SELECT DISTINCT col` | Remove duplicate rows |
 | **Limit** | `LIMIT 10` | Restrict number of rows |
 | **Offset** | `OFFSET 5` | Skip first N rows (Pagination) |
 | **Order** | `ORDER BY price DESC` | Sort by field (ASC/DESC) |

package/bin/sawit-server.js

@@ -20,7 +20,16 @@ const path = require('path');
 const config = {
     port: process.env.SAWIT_PORT || 7878,
     host: process.env.SAWIT_HOST || '0.0.0.0',
-    dataDir: process.env.SAWIT_DATA_DIR || path.join(__dirname, '../data')
+    dataDir: process.env.SAWIT_DATA_DIR || path.join(__dirname, '../data'),
+    // WAL Configuration
+    wal: {
+        enabled: process.env.SAWIT_WAL_ENABLED !== 'false', // Default true if not explicitly false
+        syncMode: process.env.SAWIT_WAL_SYNC_MODE || 'normal',
+        checkpointInterval: parseInt(process.env.SAWIT_WAL_CHECKPOINT_INTERVAL) || 10000
+    },
+    // Multi-Threading Configuration
+    clusterMode: process.env.SAWIT_CLUSTER_MODE === 'true',
+    workerCount: parseInt(process.env.SAWIT_CLUSTER_WORKERS) || 0
 };
 
 // Parse authentication if provided
@@ -37,6 +46,8 @@ console.log(`  - Port: ${config.port}`);
 console.log(`  - Host: ${config.host}`);
 console.log(`  - Data Directory: ${config.dataDir}`);
 console.log(`  - Auth: ${config.auth ? 'Enabled' : 'Disabled'}`);
+console.log(`  - WAL: ${config.wal.enabled ? 'Enabled (' + config.wal.syncMode + ')' : 'Disabled'}`);
+console.log(`  - Mode: ${config.clusterMode ? 'CLUSTER (Workers: ' + (config.workerCount || 'Auto') + ')' : 'SINGLE THREAD'}`);
 console.log('');
 
 // Create and start server

package/cli/benchmark.js

@@ -0,0 +1,318 @@
+const SawitDB = require('../src/WowoEngine');
+const SawitClient = require('../src/SawitClient');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+// Configuration
+const args = process.argv.slice(2);
+const IS_SPAWN = args.includes('--spawn');
+const IS_REMOTE = args.includes('--remote') || IS_SPAWN; // Spawn implies remote access
+const IS_CLUSTER = args.includes('--cluster');
+
+// Parsing Arguments
+const getArg = (name, def) => {
+    const found = args.find(a => a.startsWith(name + '='));
+    return found ? parseInt(found.split('=')[1]) : def;
+};
+
+const WORKER_COUNT = getArg('--workers', 1);       // Server Workers
+const CLIENT_COUNT = getArg('--clients', 1);       // Benchmark Clients (Concurrency)
+
+// Connection Settings
+const REMOTE_HOST = process.env.SAWIT_HOST || '127.0.0.1';
+const REMOTE_PORT = IS_SPAWN ? 7979 : (process.env.SAWIT_PORT || 7878); // Use custom port if spawning to avoid conflict
+
+// Local/Temp Paths
+const DB_PATH = './data/accurate_benchmark.sawit';
+const SPAWN_DATA_DIR = path.join(__dirname, '../data_bench_temp');
+
+console.log("=".repeat(80));
+console.log(`BENCHMARK - ${IS_SPAWN ? 'AUTO-SPAWNED SERVER' : (IS_REMOTE ? 'REMOTE MODE' : 'LOCAL EMBEDDED MODE')}`);
+if (IS_SPAWN) console.log(`Server Mode: ${IS_CLUSTER ? 'CLUSTER' : 'SINGLE THREAD'} (Workers: ${WORKER_COUNT})`);
+console.log(`Load: ${CLIENT_COUNT} concurrent client(s)`);
+console.log("=".repeat(80));
+
+const TARGET_TPS = 3000;
+const N = 10000;
+
+let serverProcess = null;
+
+async function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function startServer() {
+    console.log("[Setup] Spawning temporary server...");
+
+    // Cleanup temp dir
+    if (fs.existsSync(SPAWN_DATA_DIR)) {
+        fs.rmSync(SPAWN_DATA_DIR, { recursive: true, force: true });
+    }
+    fs.mkdirSync(SPAWN_DATA_DIR, { recursive: true });
+
+    const serverPath = path.join(__dirname, '../src/SawitServer.js');
+
+    return new Promise((resolve, reject) => {
+        serverProcess = spawn('node', [serverPath], {
+            env: {
+                ...process.env,
+                SAWIT_PORT: REMOTE_PORT,
+                SAWIT_HOST: REMOTE_HOST,
+                SAWIT_CLUSTER_MODE: IS_CLUSTER.toString(),
+                SAWIT_CLUSTER_WORKERS: WORKER_COUNT.toString(),
+                SAWIT_DATA_DIR: SPAWN_DATA_DIR,
+                SAWIT_LOG_LEVEL: 'info'
+            },
+            stdio: ['ignore', 'pipe', 'inherit'] // pipe stdout to check readiness
+        });
+
+        let ready = false;
+        serverProcess.stdout.on('data', (data) => {
+            const out = data.toString();
+            // console.log('[SERVER]', out.trim()); // Debug
+            if (out.includes('Ready to accept connections')) {
+                if (!ready) {
+                    ready = true;
+                    console.log("[Setup] Server Ready!");
+                    resolve();
+                }
+            }
+        });
+
+        serverProcess.on('error', (err) => reject(err));
+
+        // Timeout safety
+        setTimeout(() => {
+            if (!ready) {
+                console.error("[Setup] Server timed out starting.");
+                if (serverProcess) serverProcess.kill();
+                reject(new Error("Server startup timeout"));
+            }
+        }, 10000);
+    });
+}
+
+async function main() {
+    let db;
+    let clients = [];
+
+    // --- SETUP ---
+    if (IS_SPAWN) {
+        await startServer();
+        // Give it a tiny bit more grace period for workers to settle
+        await sleep(1000);
+    }
+
+    console.log("Setting up...");
+
+    if (IS_REMOTE) {
+        // Init remote clients
+        for (let i = 0; i < CLIENT_COUNT; i++) {
+            const client = new SawitClient(`sawitdb://${REMOTE_HOST}:${REMOTE_PORT}/benchmark_db`);
+            await client.connect();
+            // Use same DB for standard benchmark
+            try {
+                await client.query(`BUKA WILAYAH benchmark_db`);
+            } catch (e) { } // Exists
+            await client.use('benchmark_db');
+            clients.push(client);
+        }
+        db = clients[0]; // Primary for setup
+    } else {
+        // Local Setup
+        if (fs.existsSync(DB_PATH)) fs.unlinkSync(DB_PATH);
+        if (fs.existsSync(DB_PATH + '.wal')) fs.unlinkSync(DB_PATH + '.wal');
+
+        db = new SawitDB(DB_PATH, {
+            wal: {
+                enabled: process.env.WAL !== 'false',
+                syncMode: process.env.WAL_MODE || 'normal',
+                checkpointInterval: 10000
+            }
+        });
+    }
+
+    // Cleanup & Init
+    try {
+        if (IS_REMOTE) await query(db, 'DROP TABLE products');
+    } catch (e) { }
+
+    await query(db, 'CREATE TABLE products');
+
+    console.log("Populating initial data...");
+    for (let i = 0; i < N; i++) {
+        const price = Math.floor(Math.random() * 1000) + 1;
+        await query(db, `INSERT INTO products (id, price) VALUES (${i}, ${price})`);
+    }
+    await query(db, 'CREATE INDEX ON products (id)');
+    console.log("✓ Setup complete\n");
+
+    // --- PREPARE DATA ---
+    const selectQueries = [];
+    const updateQueries = [];
+    for (let i = 0; i < 1000; i++) {
+        const id = Math.floor(Math.random() * N);
+        selectQueries.push(`SELECT * FROM products WHERE id = ${id}`);
+        updateQueries.push(`UPDATE products SET price = ${Math.floor(Math.random() * 1000)} WHERE id = ${id}`);
+    }
+
+    const insertQueries = [];
+    for (let i = 0; i < 1000; i++) {
+        insertQueries.push(`INSERT INTO products (id, price) VALUES (${N + i}, 999)`);
+    }
+
+    const deleteQueries = [];
+    for (let i = 0; i < 500; i++) {
+        deleteQueries.push(`DELETE FROM products WHERE id = ${N + i}`);
+    }
+
+    // --- RUN BENCHMARKS ---
+    const results = [];
+
+    // Helper to distribute work
+    async function runParallel(name, queryList, targetTps) {
+        // Warmup
+        await query(db, queryList[0]);
+
+        const start = Date.now();
+        const totalOps = queryList.length;
+
+        // Chunk queries for workers
+        const chunkSize = Math.ceil(totalOps / (IS_REMOTE ? CLIENT_COUNT : 1));
+        const promises = [];
+
+        if (IS_REMOTE) {
+            for (let i = 0; i < CLIENT_COUNT; i++) {
+                const client = clients[i];
+                const startIdx = i * chunkSize;
+                const endIdx = Math.min(startIdx + chunkSize, totalOps);
+                const workerQueries = queryList.slice(startIdx, endIdx);
+
+                if (workerQueries.length === 0) continue;
+
+                promises.push((async () => {
+                    for (const q of workerQueries) await client.query(q);
+                })());
+            }
+        } else {
+            promises.push((async () => {
+                for (const q of queryList) await query(db, q);
+            })());
+        }
+
+        await Promise.all(promises);
+
+        const time = Date.now() - start;
+        const tps = Math.round(totalOps / (time / 1000));
+        const avg = (time / totalOps).toFixed(3);
+        const status = tps >= targetTps ? '✅ PASS' : '❌ FAIL';
+        const pct = Math.round((tps / targetTps) * 100);
+
+        return { name, tps, avg, target: targetTps, status, pct };
+    }
+
+    results.push(await runParallel('INSERT', insertQueries, TARGET_TPS));
+
+    // Cleanup inserts for delete test consistency? 
+    // Actually we keep them for SELECT/UPDATE test?
+    // Benchmark sequence: INSERT -> SELECT -> UPDATE -> DELETE
+
+    results.push(await runParallel('SELECT (indexed)', selectQueries, TARGET_TPS));
+    results.push(await runParallel('UPDATE (indexed)', updateQueries, TARGET_TPS));
+
+    // Prepare data for delete (need to ensure rows exist)
+    // We inserted 1000 new rows in INSERT test (id N to N+999).
+    // DELETE test removes 500 of them.
+    results.push(await runParallel('DELETE (indexed)', deleteQueries, TARGET_TPS));
+
+
+    // --- REPORT ---
+    console.log("=".repeat(100));
+    console.log("RESULTS");
+    console.log("=".repeat(100));
+    console.log("┌────────────────────────────┬──────────┬──────────┬────────┬─────────┬────────┐");
+    console.log("│ Operation                  │   TPS    │ Avg (ms) │ Target │   %     │ Status │");
+    console.log("├────────────────────────────┼──────────┼──────────┼────────┼─────────┼────────┤");
+
+    let passCount = 0;
+    for (const r of results) {
+        const name = r.name.padEnd(26);
+        const tps = r.tps.toString().padStart(8);
+        const avg = r.avg.padStart(8);
+        const target = r.target.toString().padStart(6);
+        const pct = (r.pct + '%').padStart(7);
+        const status = r.status.padEnd(6);
+        if (r.status.includes('PASS')) passCount++;
+        console.log(`│ ${name} │ ${tps} │ ${avg} │ ${target} │ ${pct} │ ${status} │`);
+    }
+    console.log("└────────────────────────────┴──────────┴──────────┴────────┴─────────┴────────┘");
+
+    // TEARDOWN
+    if (IS_REMOTE) {
+        // Fetch Worker Stats
+        try {
+            const adminClient = clients[0];
+            const stats = await adminClient.stats();
+
+            if (stats && stats.workers) {
+                console.log("\nWORKER STATS (Load Balance Check)");
+                console.log("=".repeat(50));
+                console.log("┌───────────┬────────────────────┬──────────┐");
+                console.log("│ Worker ID │ Queries Processed  │ Active   │");
+                console.log("├───────────┼────────────────────┼──────────┤");
+
+                let total = 0;
+                for (const w of stats.workers) {
+                    const id = w.id.toString().padEnd(9);
+                    const count = w.queries.toString().padEnd(18);
+                    const active = (w.active || 0).toString().padEnd(8);
+                    console.log(`│ ${id} │ ${count} │ ${active} │`);
+                    total += w.queries;
+                }
+                console.log("├───────────┼────────────────────┼──────────┤");
+                console.log(`│ TOTAL     │ ${total.toString().padEnd(18)} │ -        │`);
+                console.log("└───────────┴────────────────────┴──────────┘\n");
+            }
+        } catch (e) {
+            console.log("Failed to fetch worker stats:", e.message);
+        }
+
+        for (const c of clients) {
+            // Silence errors during teardown (prevents ECONNRESET logs when server is killed)
+            if (c.socket) {
+                c.socket.removeAllListeners('error');
+                c.socket.on('error', () => { }); // Catch-all for teardown errors
+            }
+            c.disconnect();
+        }
+    } else {
+        db.close();
+        if (fs.existsSync(DB_PATH)) fs.unlinkSync(DB_PATH);
+    }
+
+    if (serverProcess) {
+        console.log("Stopping server...");
+        serverProcess.kill();
+        await sleep(500);
+        // Cleanup temp dir
+        try { if (fs.existsSync(SPAWN_DATA_DIR)) fs.rmSync(SPAWN_DATA_DIR, { recursive: true, force: true }); } catch (e) { }
+    }
+}
+
+// Wrapper for async/sync agnostic call
+async function query(dbInst, q) {
+    if (dbInst.query.constructor.name === "AsyncFunction") {
+        return await dbInst.query(q);
+    } else {
+        // Check if remote client (SawitClient has async query)
+        if (IS_REMOTE) return await dbInst.query(q);
+        return dbInst.query(q);
+    }
+}
+
+main().catch(err => {
+    console.error(err);
+    if (serverProcess) serverProcess.kill();
+    process.exit(1);
+});