SawitDB - Documentation

Introduction

SawitDB is a revolutionary database solution stored in single .sawit binary files. It combines the reliability of a Paged Heap File architecture with the charm of localized wisdom.

What differentiates SawitDB is its unique Agricultural Query Language (AQL), which replaces standard SQL keywords with Indonesian farming terminology, making database management as intuitive as managing a plantation.

🚨 Emergency: Aceh Flood Relief

Please support our brothers and sisters in Aceh.

Donate via Kitabisa

Features

Paged Architecture

Data stored in 4096-byte binary pages. Optimized for low memory footprint.

Single File Storage

All data, schema, and indexes reside in a single .sawit file.

High Stability

Uses 4KB atomic pages. More stable than a coalition government.

Anti-Korupsi Integrity

Strict fsync protocols ensure data is safe and never "mysteriously disappears".

Crash Recovery

Powered by Write-Ahead Logging (WAL). Data guarantees to return. Unlike a fugitive who is "hard to find".

Zero Bureaucracy

Pure Node.js. Zero dependencies. No "Vendor Pengadaan" or markups.

True Multi-Threading

Worker Pool architecture separates IO from Compute. High concurrency with auto-healing workers.

Transparansi

Clear query language. No "Pasal Karet" (ambiguous laws).

Benchmark Performance

Environment: Single Thread, Windows Node.js (Local NVMe)

Operation	Ops/Sec	Latency (avg)
INSERT	~22,000	0.045 ms
SELECT (PK Index)	~247,288	0.004 ms
SELECT (Scan)	~13,200	0.075 ms
UPDATE (Indexed)	~11,000	0.090 ms
DELETE (Indexed)	~19,000	0.052 ms

Filosofi

Filosofi (ID)

SawitDB dibangun dengan semangat "Kemandirian Data". Kami percaya database yang handal tidak butuh Infrastruktur Langit yang harganya triliunan tapi sering down. Berbeda dengan proyek negara yang mahal di budget tapi murah di kualitas, SawitDB menggunakan arsitektur Single File yang hemat biaya.

Philosophy (EN)

SawitDB is built with the spirit of "Data Sovereignty". We believe a reliable database doesn't need "Sky Infrastructure" that costs trillions yet goes down often. SawitDB uses a cost-effective Single File architecture. Data integrity is non-negotiable.

Installation

Node.js

details


                            npm install @wowoengine/sawitdb

PHP

details


                            composer require wowoengine/sawitdb-php

Node.js Usage


                                const SawitDB = require('@wowoengine/sawitdb');

                                const path = require('path');


                                // Initialize

                                const db = new SawitDB('plantation.sawit');

PHP Usage


                                use WowoEngine\SawitDB\SawitDB;


                                // Initialize

                                $db = new SawitDB('plantation.sawit');

Build from Source (Git)


                                git clone https://github.com/WowoEngine/SawitDB.git

                                cd SawitDB && npm install

Query Syntax (AQL)

SawitDB uses intuitive farming metaphors for all database operations. It also supports Generic SQL for easier adoption.

Dual Syntax Comparison

Operation	Agricultural Query Language (AQL)	Generic SQL (Standard)
Create DB	BUKA WILAYAH sales_db	CREATE DATABASE sales_db
Use DB	MASUK WILAYAH sales_db	USE sales_db
Show DBs	LIHAT WILAYAH	SHOW DATABASES
Create Table	LAHAN products	CREATE TABLE products
Insert	TANAM KE products (...) BIBIT (...)	INSERT INTO products (...) VALUES (...)
Select	PANEN * DARI products ...	SELECT * FROM products ...
Update	PUPUK products DENGAN ...	UPDATE products SET ...
Delete	GUSUR DARI products ...	DELETE FROM products ...

Management

Create Table

LAHAN [name]

Show Tables

LIHAT LAHAN

Drop Table

BAKAR LAHAN [name]

Data Manipulation

Insert (Plant)

TANAM KE [table] (cols) BIBIT (vals)

Select (Harvest)

PANEN * DARI [table] DIMANA [cond]

Update (Fertilize)

PUPUK [table] DENGAN x=y DIMANA [cond]

Delete (Evict)

GUSUR DARI [table] DIMANA [cond]

// Create Land LAHAN sawit_blok_a // Plant Seeds (Insert) TANAM KE sawit (id, bibit, umur) BIBIT (1, 'Tenera', 5) // Harvest (Select) PANEN * DARI sawit DIMANA umur > 3 // Fertilize (Update) PUPUK sawit DENGAN status='Panen' DIMANA umur >= 10 // Evict (Delete) GUSUR DARI sawit DIMANA id = 99

Supported Operators

Operator	Syntax Example	Description
Comparison	=, !=, >, <, >=, <=	Standard value comparison
Logical	AND, OR	Combine multiple conditions
In List	IN ('coffee', 'tea')	Matches any value in the list
Pattern	LIKE 'Jwa%'	Wildcard matching (%)
Range	BETWEEN 10 AND 50	Inclusive range check
Null Check	IS NULL, IS NOT NULL	Check for existence
Pagination	LIMIT 10 OFFSET 5	Restrict and skip rows
DISTINCT	SELECT DISTINCT col	Remove duplicate rows
LEFT JOIN	LEFT JOIN ... ON ...	Include unmatched left rows
RIGHT JOIN	RIGHT JOIN ... ON ...	Include unmatched right rows
CROSS JOIN	CROSS JOIN table	Cartesian product
HAVING	GROUP BY x HAVING count > 5	Filter after aggregation
EXPLAIN	EXPLAIN SELECT ...	Show query execution plan

Full Feature Comparison

Feature	Tani Edition (AQL)	Generic SQL	Notes
Create DB	BUKA WILAYAH [db]	CREATE DATABASE [db]	Creates .sawit file
Show Tables	LIHAT LAHAN	SHOW TABLES	Lists tables
Aggregation	HITUNG SUM(x) DARI [t]	SELECT SUM(x) FROM [t]	COUNT, SUM, AVG
Index	INDEKS [t] PADA [f]	CREATE INDEX ON [t] ([f])	B-Tree Indexing
MIN/MAX	HITUNG MIN(x) DARI [t]	SELECT MIN(x) FROM [t]	Aggregation
DISTINCT	PANEN UNIK x DARI [t]	SELECT DISTINCT x FROM [t]	Unique rows
LEFT JOIN	GABUNG KIRI	LEFT JOIN ... ON ...	Outer join
RIGHT JOIN	GABUNG KANAN	RIGHT JOIN ... ON ...	Outer join
CROSS JOIN	GABUNG SILANG	CROSS JOIN	Cartesian product
HAVING	PUNYA count > 5	HAVING count > 5	Filter groups
EXPLAIN	JELASKAN SELECT ...	EXPLAIN SELECT ...	Query plan

Network

NEW

Connect using the sawitdb:// protocol and manage your data remotely.

Connection

sawitdb://host:port/database

Advanced Features

Multi-database Support
B-Tree Indexing
Aggregations (COUNT, SUM, etc.)
Optional Authentication

Start Server

node bin/sawit-server.js --port 7878

Environment Variables

SAWIT_PORT=7878

SAWIT_HOST=0.0.0.0

SAWIT_DATA_DIR=./data

SAWIT_AUTH=user:pass

Client API

Node.js Integration

SawitDB provides a clean, promise-based client for Node.js applications.

const client = new SawitClient('sawitdb://localhost:7878');
await client.connect();

// Switch DB
await client.use('production');

// Query
const profit = await client.query(
    "HITUNG SUM(total) DARI sales"
);

CLI Tools

Manage & Benchmark

Interactive Shell cli/remote.js

Connect to remote server. Supports USE [db] context switching.
Unit Tests cli/test.js

Run 17+ automated test suites covering CRUD, JOINs, DISTINCT, HAVING, EXPLAIN, and more.
Benchmark cli/benchmark.js

Test throughput. Measures INSERT (~38k TPS) and SELECT (~120k TPS) performance.

Latest Updates

v2.6.0

Upcoming! Coming Soon

True Multi-Threading: Worker Pool architecture with Least-Busy Load Balancing & Auto-Healing.
SQL Features:
- JOINs: LEFT, RIGHT, FULL OUTER, CROSS (GABUNG...).
- DISTINCT: Remove duplicate rows.
- HAVING: Filter grouped results.
- EXPLAIN: Analyze query plans.
Security: SHA-256 Hashing, Timing-Safe Auth, Input Validation, Regex Injection Fix.
Performance: Query Cloning (vs JSON.parse), True LRU Cache, B-Tree Binary Search, Optimized Aggregates.
Bug Fixes: Fixed _deleteFullScan, code duplication, AVG division by zero, and buffer leaks.

v2.5.0

Jan 2026

Performance: Object Caching & Async WAL achieved ~247,000 TPS for reads.
Hash Join: Complex joins are now 77x Faster (O(M+N)).
New Tools: Added CLI Unit Tests and Benchmarking Tool.
Persistence Fix: Fixed Index loss on restart.

v2.4

Jan 2026

Security: Full Parameterized Query support.
Docs: Enhanced documentation site.

v2.3

Dec 2025

Generic Syntax: Added SQL Standard compatibility.
Operators: Added LIKE, IN, BETWEEN support.