SawitDB

SawitDB

SawitDB is a unique database solution stored in .sawit binary files.

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 available on NPM! Connect via TCP using sawitdb:// protocol.

** Emergency: Aceh Flood Relief** Please support our brothers and sisters in Aceh. Organized by Human Initiative Aceh

Features

• 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.
• AKAD Transactions (v3.0): ACID-compliant transactions with MULAI AKAD, SAHKAN, BATALKAN.
• TEROPONG Views (v3.0): Virtual tables with PASANG TEROPONG and BUANG TEROPONG.
• KENTONGAN Triggers (v3.0): Event hooks for INSERT/UPDATE/DELETE.
• SOP Procedures (v3.0): Stored scripts with SIMPAN SOP and JALANKAN SOP.
• CABANG Replication (v3.0): Primary-Replica synchronization via Change Data Capture.
• DB Event & CDC (v3.0): Change Data Capture with CPO adapter and custom event hooks (OnTableCreated, OnTableInserted, etc).
• BLUSUKAN Full-Text Search (v3.0): Inverted Index search with BLUSUKAN KE ... CARI.
• POS RONDA Security (v3.0): Role-Based Access Control with BERI IZIN and CABUT IZIN.

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 (.sawit) yang hemat biaya. Backup cukup copy-paste, tidak perlu sewa vendor konsultan asing. Fitur fsync kami menjamin data tertulis di disk, karena bagi kami, integritas data adalah harga mati, bukan sekadar bahan konferensi pers untuk minta maaf.

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. Unlike state projects that are expensive in budget but cheap in quality, SawitDB uses a cost-effective Single File (.sawit) architecture. Backup is just copy-paste, no need to hire expensive foreign consultants. Our fsync feature guarantees data is written to disk, because for us, data integrity is non-negotiable, not just material for a press conference to apologize.

File List

• 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/: Command Line Interface tools (local, remote, test, bench).
• CHANGELOG.md: Version history.
• docs/DB_Event: Database Event Documentation.

Installation

Install via NPM:

npm install @wowoengine/sawitdb

Quick Start

1. Start the Server

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

You can use the built-in CLI tool:

node cli/remote.js

Or use the SawitClient class in your Node.js application.

Dual Syntax Support

SawitDB introduces the Generic Syntax alongside the classic Agricultural Query Language (AQL), making it easier for developers familiar with standard SQL to adopt.

Query Syntax (Detailed)

1. Management Commands

Create Table

-- Tani
LAHAN users
-- Generic
CREATE TABLE users

Show Tables

-- Tani
LIHAT LAHAN
-- Generic
SHOW TABLES

Drop Table

-- Tani
BAKAR LAHAN users
-- Generic
DROP TABLE users

2. Data Manipulation

Insert Data

-- Tani
TANAM KE users (name, role) BIBIT ('Alice', 'Admin')
-- Generic
INSERT INTO users (name, role) VALUES ('Alice', 'Admin')

Select Data

-- Tani
PANEN name, role DARI users DIMANA role = 'Admin' ORDER BY name ASC LIMIT 10
-- Generic
SELECT name, role FROM users WHERE role = 'Admin' ORDER BY name ASC LIMIT 10

Operators: =, !=, >, =, ` 5

#### DISTINCT
```sql
SELECT DISTINCT category FROM products
-- Returns only unique values

JOIN Types

-- 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

EXPLAIN SELECT * FROM users WHERE id = 5
-- Returns execution plan: scan type, index usage, join methods

4. Transactions (AKAD)

Syntax

-- Tani (AQL)
MULAI AKAD
TANAM KE ...
SAHKAN
BATALKAN

-- Generic
BEGIN TRANSACTION
INSERT INTO ...
COMMIT
ROLLBACK

Example

db.query('MULAI AKAD');
db.query("TANAM KE Users (name) BIBIT ('Alice')");
db.query("TANAM KE Users (name) BIBIT ('Bob')");
db.query('SAHKAN');

5. Views (TEROPONG)

Syntax

-- Tani (AQL)
PASANG TEROPONG [name] SEBAGAI [query]
PANEN * DARI [name]
BUANG TEROPONG [name]

-- Generic
CREATE VIEW [name] AS [query]
SELECT * FROM [name]
DROP VIEW [name]

Example

// Create View
db.query("PASANG TEROPONG ActiveUsers SEBAGAI PANEN * DARI Users DIMANA status = 'active'");

// Query View
const active = db.query('PANEN * DARI ActiveUsers');

6. Triggers (KENTONGAN)

Syntax

-- Tani (AQL)
PASANG KENTONGAN [nama] PADA [event] [table] LAKUKAN [query]
BUANG KENTONGAN [nama]

-- Generic (Mapped)
CREATE TRIGGER [nama] ON [event] [table] DO [query]
DROP TRIGGER [nama]

Example

PASANG KENTONGAN LogInsert PADA INSERT users LAKUKAN TANAM KE logs (msg) BIBIT ('New User Inserted')

7. Stored Procedures (SOP)

Syntax

-- Tani (AQL)
SIMPAN SOP [nama] SEBAGAI [query]
JALANKAN SOP [nama]
BUANG SOP [nama]

-- Generic (Mapped)
CREATE PROCEDURE [nama] AS [query]
EXECUTE PROCEDURE [nama]
DROP PROCEDURE [nama]

Example

SIMPAN SOP ArchiveUsers SEBAGAI TANAM KE archive SELECT * FROM users WHERE status='deleted'
JALANKAN SOP ArchiveUsers

8. Replication (CABANG)

Syntax

-- Tani (AQL)
SETEL CABANG SEBAGAI [role] [host] [port]

-- Roles:
-- PRIMARY / PUSAT : The master database
-- REPLICA / CABANG : The slave database

Example

-- On Master
SETEL CABANG SEBAGAI PRIMARY

-- On Slave
SETEL CABANG SEBAGAI REPLICA 192.168.1.100 7878

9. BLUSUKAN (Full-Text Search)

Syntax

-- Tani (AQL)
BLUSUKAN KE [table] CARI "[term]"

-- Generic
SEARCH [table] "[term]"
FULLTEXT [table] "[term]"

Example

BLUSUKAN KE products CARI "sawit"
-- Returns all rows in 'products' containing "sawit" in any text field.

10. POS RONDA (Security)

Syntax

-- Tani (AQL)
BERI IZIN [action] KEPADA [user] DI [table]
CABUT IZIN [action] DARI [user] DI [table]

-- Generic
GRANT [action] ON [table] TO [user]
REVOKE [action] ON [table] FROM [user]

Actions

• read: SELECT, SEARCH
• write: INSERT, UPDATE, DELETE
• all: All permissions

Example

BERI IZIN read KEPADA 'guest' DI products
REVOKE write ON users FROM 'intern'

…

env
SAWIT_CDC_FILE=./examples/logs/sawit.cpo
SAWIT_CDC_ADAPTER=cpo

Note: Kafka support coming soon.

Custom Event Handler

You can use a custom event handler by passing it to the constructor:

const CustomHandler = require('./dbeventHandlerExample');
const db = new SawitDB(dbPath, { dbevent: new CustomHandler() });

Architecture Details

• 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